Custom instructions and prompts

agentic_options.custom_prompt lets you instruct the Parse agentic model the way you would instruct an LLM: name the document type, say what to focus on or skip, ask for a format to be preserved. The prompt shapes the markdown and items Parse produces for the job. It is available on cost_effective, agentic, and agentic_plus; the fast tier runs no agentic model and rejects agentic_options.

When to use it

• Give document context the parser cannot infer: “This is a financial 10-K”, “The provided document is a restaurant receipt”.
• Preserve a format: currency symbols on every number, dates as YYYY-MM-DD, the original section hierarchy.
• Narrow the output to the parts you care about, such as line items and the total on a receipt.
• Improve results on an unusual layout by describing it.

A prompt steers; it does not guarantee a shape. When you need JSON that always matches a schema, use Extract on the same document instead.

Options

Option	Type	Default	What it does
agentic_options.custom_prompt	string	unset	Natural-language instructions for the agentic parser, applied to the whole job. Not available on fast.

agentic_options is a top-level request field, not part of processing_options. Changing the prompt changes the parse options, so a re-run with a new prompt bypasses the result cache automatically.

Writing a prompt that works

• Be specific, and name the document type.
• Say what to skip as well as what to keep.
• Specify the output format you want where it matters.
• Keep it short: two or three sentences is the sweet spot.

Example

Parse a receipt once with no instructions, then again with a prompt that keeps only the line items and the amount due:

from llama_cloud import LlamaCloud

client = LlamaCloud()  # reads LLAMA_CLOUD_API_KEY from the environment

FILE_ID = "FILE_ID"  # a receipt image uploaded with client.files.create(file=..., purpose="parse")

vanilla = client.parsing.parse(
    file_id=FILE_ID,
    tier="agentic",
    version="latest",
    expand=["markdown"],
)
print(vanilla.markdown.pages[0].markdown)

with_prompt = client.parsing.parse(
    file_id=FILE_ID,
    tier="agentic",
    version="latest",
    agentic_options={
        "custom_prompt": (
            "The provided document is a restaurant receipt. "
            "Provide ONLY each line item (item name and price) and the final amount to be paid."
        )
    },
    expand=["markdown"],
)
print(with_prompt.markdown.pages[0].markdown)

What you get

Without instructions, the receipt example returns the whole receipt as markdown: the survey banner, the store address, an order table, totals, and the hiring notice at the bottom:

## McDonald's Restaurant #31278
2378 PINE RD NW
RICE, MN 56367-9740

| Item                     | Price |
|--------------------------|-------|
| 1 Happy Meal 6 Pc        | 4.89  |
| 1 Snack Oreo McFlurry    | 2.69  |

| Subtotal                 | 7.58  |
| Tax                      | 0.52  |
| Take-Out Total           | 8.10  |

With the prompt, the same page narrows to just the line items and the total:

* Happy Meal 6 Pc 4.89
* Snack Oreo McFlurry 2.69

Take-Out Total 8.10

The prompt in the Recipes page shows the other common pattern, keeping everything but enforcing conventions: “This is a financial 10-K. Preserve currency symbols on every number and keep the original section hierarchy.”

See also

• Parse with additional prompts: the receipt example in Python, TypeScript, Go, Java, and the CLI
• Recipes: steer the parser with a custom prompt
• Configuring Parse: custom prompt
• Tiers for which tiers run the agentic model
• Extract for schema-driven extraction with a guaranteed output shape