Writing Effective Contexts for Reindeer Agents – Reindeer

What a Context Is and Why It Matters

A context is one artifact file that gives an agent business knowledge or instructions for a specific workflow. Think of it as a document you would give a new teammate to explain one part of the job. An agent can use several contexts, with each file focused on one clear purpose.

A frontier LLM already knows how to read documents, summarize information, compare values, and extract fields. Context files provide the business knowledge a teammate would still need: policies, terminology, trusted sources, and decision rules.

Organize the Context Files

Create one context file for each clear task or topic. Write it as if you were explaining that part of the job to a teammate: when it applies, what to do, which rules to follow, and what result to produce.

Use another file for a different task or policy, or for a large reference such as a purchase-order list. This makes the content easier for people to review and update. It also lets the agent read only the relevant file at the point when it is needed.

Example: invoice approval

Suppose an agent reviews one invoice at a time and decides whether to approve or reject it. If something important is missing, don't worry: the agent can ask a human for help. A simple set of context files could include:

invoice-approval/
├── invoice_approval_policy.md
├── invoice_matching.md
├── review_handling.md
└── purchase_orders.csv

Each file has a clear role:

invoice_approval_policy.md explains the approval task, defines the case, and lists the possible decisions.
invoice_matching.md contains the checks the agent must complete before approving an invoice.
review_handling.md explains what to do when evidence is missing or sources conflict.
purchase_orders.csv contains the purchase orders exported from the ERP.

Write Effective Context Files

As mentioned above, write each context file as if you were explaining the work to a capable teammate. Focus on one logical task and describe it from start to finish: its goal, when it applies, the information and sources to use, the detailed steps to follow, the rules behind each decision, and what a correct result looks like. Use the same terms your team uses at work.

Avoid content that belongs in an AI prompt or platform configuration:

Headings such as SYSTEM, USER, or ASSISTANT
Wrappers such as <instructions> or BEGIN PROMPT
Requests such as "show your chain of thought." Ask for the decision, a short reason, and the supporting evidence instead.
Technical instructions that Reindeer already provides, such as sandbox rules, generated file paths, or instructions for returning the final result
Directions tied to the user interface, such as "open the Approval screen and click the green button." Describe the business action instead, such as "approve the invoice."

Define which source to trust

For each decision, explain which source the agent should trust when information conflicts. Name the real system, policy, or file instead of using general terms. For example:

Use the invoice for the invoice number and invoiced amount.
Use purchase_orders.csv for the purchase-order status, vendor ID, currency, and expected amount.
Use examples to understand the rules, not to create new rules or exceptions.

If required information is missing or the conflict cannot be resolved, the agent should not guess. It can use Reindeer's built-in platform tool to ask a human before continuing.

Be clear about required instructions

Tell the agent which instructions it must follow every time. Use words such as must, always, and never only for rules that are truly non-optional, such as a required source, check, tool, action, or order of steps.

Do not mark every instruction as mandatory. Too many hard rules make the important ones harder to spot, can create conflicts, and may cause the agent to overdo the task. Use plain, direct language for everything else. When a decision requires judgment, explain which facts matter and what outcome you expect.

Be exact when exactness matters

If your business expects an exact format, structure, name, calculation, or limit, write it down. Do not assume the agent will choose the same convention. For example:

Format dates as YYYY-MM-DD.
Format an email subject as Invoice review - {invoice_number} - {decision}.
Treat two amounts as matching only when |expected - actual| < 0.01.
Use SoFi Inc. as the approved vendor name instead of variants such as Sofi or Sofi INC..

Also define required fields, allowed values, validation checks, completion conditions, and who should handle exceptions. Keep a short list in the context file that uses it. Put a large list or mapping in a separate data context file, such as purchase_orders.csv.

Define what one Case represents

In Reindeer, a Case is the saved record for one business item the Agent works on, such as an invoice, shipment, order, or email thread. It is usually one row that a user reviews. A Case stays available across Agent runs, so later runs can update it with new information or a new decision.

In the context file, define:

What one Case represents
Which business identifier is used to recognize it, such as an invoice number or order reference
Which details, status, and decision the Case should keep
When the Agent should update the Case
When the Case is complete

Keep related parts, such as invoice lines and attachments, inside the same Case.

Match the Format to the Content

Formatting is part of the instruction. It helps the agent understand how information is organized and how different pieces of information relate to each other. Use the format that best matches the content:

Headings separate topics.
Bulleted lists group related rules or concepts.
Numbered lists define steps that must happen in sequence.
Code blocks preserve exact text, templates, commands, or examples.

Protect sensitive data

Do not place passwords, API keys, or unnecessary personal data in context files.

Example Context Files

The invoice approval workflow uses four context files. The main policy defines the overall flow, while the other files provide matching rules, human-help instructions, and purchase-order data.

invoice_approval_policy.md

# Invoice Approval

## Goal

Decide whether to approve or reject an invoice.

## Case

One Case represents one invoice. The vendor ID and invoice number together are
its business identifier.

The Case contains:

- Invoice details: invoice number, invoice date, vendor ID, vendor name,
  currency, total, and purchase-order number
- Invoice lines: description, quantity, unit price, and line total
- Source references: the invoice and its attachments
- Matching checks: the result of each check (`Passed`, `Failed`, or
  `Waiting for information`), including the expected and actual values
- Final decision: `Approved` or `Rejected`, with the reason and supporting
  evidence

## Workflow

1. Read the invoice and collect the information defined in the Case.
2. Find the Case with the same vendor ID and invoice number, or create it.
3. Match the invoice to its purchase order using `purchase_orders.csv` and
   apply the checks in `invoice_matching.md`.
4. If missing or conflicting information prevents a check, follow
   `review_handling.md` and continue after the human responds.
5. Set the decision to `Approved` if every check passes or `Rejected` if any
   check fails. Record the decision, reason, and evidence in the Case.

invoice_matching.md

# Invoice Matching

Use these checks to match an invoice to its purchase order:

1. The purchase-order number on the invoice must identify a row in
   `purchase_orders.csv`.
2. The vendor ID and currency must match that row exactly.
3. The invoice total and purchase-order amount match when
   `|purchase_order_amount - invoice_total| < 0.01`.
4. The purchase-order status must be `Open`.

The match passes only when every check passes. If the available evidence shows
that a check failed, the match fails. If a check cannot be completed because
information is missing or conflicting, follow `review_handling.md`.

review_handling.md

# Ask for Human Help

Use this file when missing or conflicting information prevents the Agent from
completing a required check.

- Ask a human for the information needed to continue.
- Include the invoice number, the blocked check, and the missing or conflicting
  values in the request.
- Do not guess or choose between conflicting values.
- After the human responds, return to the blocked check and continue the
  workflow.

purchase_orders.csv

purchase_order_number,vendor_id,currency,purchase_order_amount,status
PO-1001,V-1001,USD,2500.00,Open
PO-1002,V-2042,EUR,980.50,Closed

How Reindeer Uses Contexts

An Agent can use several Contexts. Each Context contains one Artifact file. Publishing a Context creates a Context Version. Reindeer processes the selected Context Versions and compiles a new Agent Revision.

An Agent Revision gives each run two kinds of input. Reindeer includes the Agent instructions in the model's prompt automatically. It makes the Context files available in the run's file system, but their contents enter the model's active context only after the Agent reads or searches them.

Publishing a new Context Version does not change an existing Agent Revision. To use the new version, Reindeer must compile a new Agent Revision that includes it.

Reindeer Concepts

Agent. A workspace-scoped resource for a task or business process. The Agent keeps the same identity while its configuration changes through Agent Revisions.
Agent Revision. An immutable snapshot of the configuration used for a run, including the system prompt, model and harness settings, skills, schemas, and pinned Context Versions. Changing this configuration requires a new Agent Revision.
Artifact. A workspace-scoped file containing content such as a policy, mapping, example, image, or structured data.
Context. An Artifact file attached to an Agent as an instruction or reference.
Context Version. An immutable snapshot of one Context file. Agent Revisions pin specific Context Versions, so publishing a newer version does not change existing revisions or past runs.

Context files can contain policies (.md, .docx, .pdf), mappings and canonical values (.xlsx, .csv, .json), contacts, examples, and images.