> ## Documentation Index
> Fetch the complete documentation index at: https://reagent-ai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Contract testing for multi-agent handoffs. pytest-native assertions that catch schema drift, broken handoffs, and tool-output regressions before they ship.

## The problem

Multi-agent systems fail at the seams. One agent hands structured data to the next, and the second agent keeps running even when the shape is subtly wrong: a renamed field, a missing key, or a string where a list was expected.

In the vendor-onboarding showcase, the intake agent renames `data_access.contains_customer_pii` to `handles_personal_data` and changes `compliance.subprocessors` from `list[str]` to a comma-separated string. The downstream security review can still run, but it is now making a decision from incomplete data.

## The solution

**reagent-flow** treats every handoff as a contract and every tool call as a typed boundary. You declare the schema you expect; reagent-flow records what actually flowed and fails the test when they diverge — with an **Agent Stack Trace** pinpointing the exact field that drifted.

```python theme={null}
# Security review receives a handoff from the intake agent.
security_session.assert_handoff_matches(schema={
    "vendor_name": str,
    "data_access": {
        "contains_customer_pii": bool,
        "data_categories": [str],
    },
    "compliance": {
        "subprocessors": [str],
        "dpa_required": bool,
    },
})
```

If the upstream agent renames `contains_customer_pii` to `handles_personal_data`, this assertion fails at PR time, not after a risky vendor gets the wrong review.

## What this is

<CardGroup cols={2}>
  <Card title="CI validation" icon="check">
    Fail pull requests when agent handoff payloads or tool outputs drift from the contract you declared.
  </Card>

  <Card title="Local trace assertions" icon="terminal">
    Run in pytest with local trace files. No hosted service or production runtime layer is required.
  </Card>
</CardGroup>

## What this is not

<CardGroup cols={2}>
  <Card title="Not runtime guardrails" icon="shield-x">
    reagent-flow does not block live traffic, re-ask models, or enforce production policies.
  </Card>

  <Card title="Not semantic verification" icon="brain">
    It checks declared contracts. It does not prove that every agent decision is correct.
  </Card>
</CardGroup>

## What you get

<CardGroup cols={2}>
  <Card title="Handoff contracts" icon="handshake">
    Type-check the data passed between agents, with nested dicts, typed lists, and optional Pydantic support.
  </Card>

  <Card title="Tool output contracts" icon="file-check">
    Validate the shape of every tool's return value, catching upstream API drift before the downstream agent sees it.
  </Card>

  <Card title="Context preservation" icon="link">
    Verify specific values (IDs, versions, user refs) survive multi-hop handoffs unchanged.
  </Card>

  <Card title="Flow assertions" icon="route">
    Guarantee the tool-calling sequence you expect — order, repetition, forbidden calls.
  </Card>

  <Card title="Golden baseline diffs" icon="code-compare">
    Snapshot-test known-good traces and detect behavioral regressions from prompt tweaks.
  </Card>

  <Card title="Agent Stack Traces" icon="layer-group">
    Every failed assertion attaches a readable dump of the full tool-calling history.
  </Card>
</CardGroup>

## Key concepts

| Concept               | Description                                                                                                                                              |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Session**           | A context manager that records tool calls for one agent run; may declare a `parent_trace_id` and `handoff_context` to form a link in a multi-agent chain |
| **Handoff context**   | The structured payload passed from one agent session to the next — the target of contract assertions                                                     |
| **Trace**             | The full sequence of turns captured during a session                                                                                                     |
| **Contract**          | A declared schema (`{field: type}`) validated against a handoff or tool result                                                                           |
| **Golden baseline**   | A saved trace used as the expected behavior for future runs                                                                                              |
| **Agent Stack Trace** | A readable dump of every turn, attached to assertion failures                                                                                            |

## Framework support

reagent-flow has a **zero-dependency core** with thin adapters for the major agent frameworks:

* OpenAI
* Anthropic
* LangChain
* LangGraph
* CrewAI

<Card title="Get started" icon="rocket" href="/quickstart">
  Install reagent-flow and write your first contract test in under 5 minutes.
</Card>

<Card title="Why not guardrails?" icon="circle-help" href="/concepts/why-contract-testing">
  See how reagent-flow fits alongside structured outputs, guardrails, evals, and observability.
</Card>