---
title: Custom instructions and prompts | Developer Documentation
description: How to steer Parse output with a natural-language custom prompt in agentic_options, which tiers accept it, what it can and cannot guarantee, and the receipt example that narrows output to line items and the total.
---

`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](../../../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](../../examples/parse_with_prompts/) 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](../../guides/recipes/#steer-the-parser-with-a-custom-prompt) 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](../../examples/parse_with_prompts/): the receipt example in Python, TypeScript, Go, Java, and the CLI
- [Recipes: steer the parser with a custom prompt](../../guides/recipes/#steer-the-parser-with-a-custom-prompt)
- [Configuring Parse: custom prompt](../../guides/configuring-parse/#custom-prompt)
- [Tiers](../../guides/tiers/) for which tiers run the agentic model
- [Extract](../../../extract/) for schema-driven extraction with a guaranteed output shape