Parse Files and Query a Llama Cloud Index in Jinba Flow

Use LLAMA_CLOUD_PARSE for file text or LLAMA_CLOUD_QUERY to answer questions from a Llama Cloud index.

Jinba Flow has two Llama Cloud tools. LLAMA_CLOUD_PARSE reads a file URL and returns parsed text. LLAMA_CLOUD_QUERY sends one or more questions to an existing Llama Cloud index and returns generated answers. Both use the apiKey configuration; see Llama credentials.

Parse a file URL

LLAMA_CLOUD_PARSE requires a url input. It returns parsed text as a string in result.

- id: parse_file
  tool: LLAMA_CLOUD_PARSE
  config:
    - name: apiKey
      value: "<Llama Cloud API key>"
  input:
    - name: url
      value: "https://example.com/report.pdf"

Replace the placeholders with your key and a reachable file URL. Inspect result for extracted text. A 401 error indicates an invalid or expired key; an empty-content error means the file could not be parsed into text.

Parsing and querying are separate jobs. LLAMA_CLOUD_PARSE extracts text from the URL you provide; it does not add that document to the index used by LLAMA_CLOUD_QUERY. Upload and index documents in Llama Cloud first, then query the index by its name, project, and organization.

To extract useful sections from a one-off document, add a later AI step that depends on parse_file. This is the current equivalent of the former parse-and-process workflow:

- id: summarize_document
  tool: OPENAI_INVOKE
  needs: [parse_file]
  input:
    - name: prompt
      value: |
        From the parsed document below, list its main specifications,
        procedures, and safety warnings. Do not add details that are not
        present in the document.
        {{steps.parse_file.result}}

The AI step’s result.content contains the generated text. Review it against the parsed text before using it as instructions or reference data.

Query an existing index

LLAMA_CLOUD_QUERY requires the index name, projectName, organizationId, and positive similarityTopK. The input field is an array of questions. Optional systemPrompt defaults to {query} and can include that placeholder to insert each question.

- id: query_index
  tool: LLAMA_CLOUD_QUERY
  config:
    - name: apiKey
      value: "<Llama Cloud API key>"
  input:
    - name: input
      value: '["What changed in the report?"]'
    - name: name
      value: "<index name>"
    - name: projectName
      value: "<project name>"
    - name: organizationId
      value: "<organization ID>"
    - name: similarityTopK
      value: 5

Replace the index details with an index you can access. similarityTopK sets how many similar chunks are retrieved for each question; start with a small value and increase it if answers are missing relevant context. systemPrompt defaults to {query}; add instructions around that placeholder to set the answer style, but keep the user’s question in the prompt.

The output result is an array with one entry per question. Each entry is an array whose first string is the submitted question, second is the generated answer, and remaining strings are source excerpts prefixed by file name when available. Use the answer for a summary, and keep the excerpts with it when a person needs to check the source. A failed individual query is returned as an error string in that entry, so inspect results before treating every answer as successful.

You can send several related questions in one call by adding them to the input array, for example ["What changed this quarter?","Which risks are still open?"]. Each question is answered against the configured index. If you need to compare separate indexes, create a query step for each index and give each step its own name and index details.

For a comparison, use the same question and retrieval count in both steps, changing only the index details. Then pass both results to a later step and ask it to separate shared findings from differences. This makes the index the comparison variable and keeps the questions aligned. Keep in mind that the query tool generates answers from retrieved text; verify important claims against the returned source excerpts and the original documents.

Practical guidance

• Organize indexed documents by topic or use case so each query targets a relevant collection.
• Ask focused questions that name the subject, period, or document type you need.
• Use several questions in one call for a small related set; split unrelated work so each prompt can give useful context.
• Treat retrieved excerpts as evidence to review. The answer is generated text and can omit nuance or disagree with the source.
• If answers are empty or off-topic, confirm the index contains the expected documents, check the organization and project, and adjust the question or similarityTopK.
• Keep the API key in Jinba’s secret configuration. Do not paste it into workflow prompts or public examples.

Build a question-and-answer workflow

For a small FAQ or review, put the questions in one input array. LLAMA_CLOUD_QUERY processes the questions in parallel and keeps their order in the result. Set systemPrompt once to give every question the same answer rules:

- id: answer_review_questions
  tool: LLAMA_CLOUD_QUERY
  config:
    - name: apiKey
      value: "<Llama Cloud API key>"
  input:
    - name: input
      value: '["What are the main findings?","Which risks need follow-up?","What evidence supports each finding?"]'
    - name: systemPrompt
      value: "Answer from the indexed documents. Be concise, state when the documents do not contain the answer, and include relevant source details. Question: {query}"
    - name: name
      value: "<index name>"
    - name: projectName
      value: "<project name>"
    - name: organizationId
      value: "<organization ID>"
    - name: similarityTopK
      value: 5

Review each question’s result entry individually. A useful answer should address the question, and the trailing source excerpts should support the main points. If the index cannot answer a question, the prompt asks it to say so instead of filling the gap with a guess.

Compare two indexes

When the same question should be answered from two collections—for example, a product manual and a support archive—make two query steps. Give both steps the same question, systemPrompt, and similarityTopK; change name and other index identifiers to target the second collection. A later OPENAI_INVOKE step can summarize the two answer entries and their source excerpts, calling out agreement, differences, and missing evidence. Keep the source excerpts in that synthesis input so it can distinguish a disagreement in the documents from a difference in generated wording.

For example, answer the same question from a manual index and a support-archive index, then compare them:

- id: query_manual
  tool: LLAMA_CLOUD_QUERY
  config:
    - name: apiKey
      value: "<Llama Cloud API key>"
  input:
    - name: input
      value: '["How do I reset the device to factory settings?"]'
    - name: systemPrompt
      value: "Answer only from the indexed documents. Say when they do not contain the answer. Question: {query}"
    - name: name
      value: "product-manual"
    - name: projectName
      value: "<project name>"
    - name: organizationId
      value: "<organization ID>"
    - name: similarityTopK
      value: 4

- id: query_support
  tool: LLAMA_CLOUD_QUERY
  config:
    - name: apiKey
      value: "<Llama Cloud API key>"
  input:
    - name: input
      value: '["How do I reset the device to factory settings?"]'
    - name: systemPrompt
      value: "Answer only from the indexed documents. Say when they do not contain the answer. Question: {query}"
    - name: name
      value: "support-archive"
    - name: projectName
      value: "<project name>"
    - name: organizationId
      value: "<organization ID>"
    - name: similarityTopK
      value: 4

- id: compare_answers
  tool: OPENAI_INVOKE
  needs: [query_manual, query_support]
  input:
    - name: prompt
      value: |
        Compare the two sets of answers below. Each entry is [question, answer, source excerpts...]. List where they agree, where they differ, and where one side has no supporting excerpt. Do not add facts that are not in the excerpts.
        Product manual: {{steps.query_manual.result}}
        Support archive: {{steps.query_support.result}}

Each query result keeps the question, the answer, and its source excerpts, so the comparison step can check both answers against their evidence.

This pattern is also useful for comparing document groups by period or topic. Ensure each index contains the intended documents before interpreting the comparison. The query tool does not create indexes or choose which documents belong in them.

Research one question across several indexes

A broad question, such as preparing a product launch, often needs evidence from different collections. Split it into focused questions first, send each group to the index that covers it, then combine the answers. This keeps the former contextual-research workflow with the current tool names.

- id: research_question
  tool: INPUT_TEXT
  input:
    - name: value
      value: "We are planning a healthcare AI product launch. What regulatory and market factors should we consider?"

- id: plan_queries
  tool: OPENAI_INVOKE
  needs: [research_question]
  input:
    - name: prompt
      value: |
        Break this question into focused search questions:
        {{steps.research_question.result}}
        Return 2 or 3 regulatory questions and 2 or 3 market questions.
    - name: json_schema
      value: '{"type":"object","properties":{"regulatory_queries":{"type":"array","items":{"type":"string"}},"market_queries":{"type":"array","items":{"type":"string"}}},"required":["regulatory_queries","market_queries"]}'

- id: search_regulatory
  tool: LLAMA_CLOUD_QUERY
  needs: [plan_queries]
  config:
    - name: apiKey
      value: "<Llama Cloud API key>"
  input:
    - name: input
      value: '{{steps.plan_queries.result.content.regulatory_queries}}'
    - name: systemPrompt
      value: "Answer only from the indexed documents. Say when they do not contain the answer. Question: {query}"
    - name: name
      value: "regulatory-knowledge-base"
    - name: projectName
      value: "<project name>"
    - name: organizationId
      value: "<organization ID>"
    - name: similarityTopK
      value: 4

- id: search_market
  tool: LLAMA_CLOUD_QUERY
  needs: [plan_queries]
  config:
    - name: apiKey
      value: "<Llama Cloud API key>"
  input:
    - name: input
      value: '{{steps.plan_queries.result.content.market_queries}}'
    - name: systemPrompt
      value: "Answer only from the indexed documents. Say when they do not contain the answer. Question: {query}"
    - name: name
      value: "market-intelligence-index"
    - name: projectName
      value: "<project name>"
    - name: organizationId
      value: "<organization ID>"
    - name: similarityTopK
      value: 4

- id: write_brief
  tool: OPENAI_INVOKE
  needs: [search_regulatory, search_market]
  input:
    - name: prompt
      value: |
        Write a short research brief for the question below, using only the answers and source excerpts provided. Group it into regulatory considerations, market opportunities, and open questions the documents do not answer. Name the source file for each main point when one is given.
        Question: {{steps.research_question.result}}
        Regulatory answers: {{steps.search_regulatory.result}}
        Market answers: {{steps.search_market.result}}

plan_queries uses json_schema, so its result.content is an object and each list can be passed straight to a query step’s input. Add a third query step and a third list to cover another area, such as technical requirements. The brief is generated text; check its main points against the source excerpts before sharing it.

The current tool ID is LLAMA_CLOUD_QUERY. Older LLAMA_CLOUD_QUERY_WITH_LLAMA_INDEX, LLAMA_CLOUD_SEARCH, and LLAMA_CLOUD_SEARCH_WITH_LLAMA_INDEX identifiers used by the former advanced examples are not part of the current tool set; use LLAMA_CLOUD_QUERY with the current input names above.