Examples

This section is a recipe catalog, not a loose folder dump. Each example is here to demonstrate one concrete runtime behavior, how to run it, what to inspect, and which integration problem it helps solve.

Browse by track

FundamentalsBasic AgentUnderstand the minimal loop, one tool call, and final response assembly.example:basicFundamentalsToolsSee typed local tools, env checks, and an external API-backed tool in one place.example:toolsSmart RuntimePlanning & TODOsInspect how a smart agent turns multi-step work into durable plan state.example:todo-planningSmart RuntimeUnderstand context compaction before adding retrieval and resume behaviors.example:summarizationSmart RuntimeRecover raw tool payloads after the runtime archived heavy responses.example:summarize-contextSmart RuntimeContinue on a later turn after history was already rewritten into a compact form.example:rewrite-summarySmart RuntimeSee how the runtime forces a direct answer once the tool-call budget is exhausted.example:tool-limitControl & SafetyPause before sensitive execution, then resume from an approved runtime state.example:tool-approvalControl & SafetyAsk UserPause with a structured multi-choice prompt, then resume with the user's answer.example:ask-userControl & SafetySnapshot a paused run, serialize it, and continue later without replaying the session.example:pause-resumeControl & SafetyRequire a schema-shaped final result while keeping the standard assistant response path.example:structured-outputControl & SafetyEnforce request and response policy at runtime instead of relying on prompt wording.example:guardrailsOrchestrationCompose specialist agents as tools without moving into a heavier orchestration stack.example:multi-agentOrchestrationTransfer ownership to another agent and inspect explicit handoff events.example:handoffIntegrationsStart with the smallest multimodal message format before wrapping it in a full agent.example:visionIntegrationsConnect a remote MCP server and run discovered tools inside the same smart runtime.example:mcp-tavily

1. Pick the runtime problem you are trying to solve.
2. Open the closest example page.
3. Run the script from examples/package.json.
4. Compare the documented flow with the example source and the output you see locally.

Setup once

cd examples
npm install

Some examples run entirely with fake models. Others need real provider credentials.

## Environment matrix

| Example type | Real provider key required | Notes |
|---|---|---|
| `basic`, `planning`, `summarization`, `tool-limit` | optional | These examples include a fake model fallback. |
| `tools` | `OPENAI_API_KEY` | `TAVILY_API_KEY` is optional unless the search tool is used. |
| `structured-output` | optional | Includes a fake model fallback. |
| `pause-resume`, `tool-approval`, `ask-user`, `guardrails` | no | Built for local runtime behavior inspection. |
| `multi-agent` | optional | Includes fake-model fallback. |
| `handoff` | yes | Uses `ChatOpenAI` directly. |
| `vision` | yes | Requires a multimodal-capable provider model. |
| `mcp` | yes | Requires `OPENAI_API_KEY` and `TAVILY_API_KEY`. |

## Choose by product need

| If you need to... | Open this example first |
|---|---|
| understand the minimal runtime loop | `/examples/basic` |
| define and call local typed tools | `/examples/tools` |
| make the agent manage multi-step work | `/examples/planning` |
| keep a long-running agent alive under context pressure | `/examples/summarization` |
| recover archived raw tool payloads | `/examples/summarize-context` |
| continue after compaction on a later turn | `/examples/rewrite-summary` |
| stop unbounded tool recursion | `/examples/tool-limit` |
| pause for human approval | `/examples/tool-approval` |
| ask the user a structured question | `/examples/ask-user` |
| snapshot and resume later | `/examples/pause-resume` |
| force typed final output | `/examples/structured-output` |
| block unsafe requests or responses | `/examples/guardrails` |
| compose specialist agents | `/examples/multi-agent` |
| hand off ownership to another agent | `/examples/handoff` |
| connect a remote MCP tool server | `/examples/mcp` |
| send image input to a multimodal model | `/examples/vision` |

## Suggested learning path

### 1. Fundamentals

- `basic`
- `tools`
- `planning`

### 2. Smart runtime behavior

- `summarization`
- `summarize-context`
- `rewrite-summary`
- `tool-limit`

### 3. Production control surfaces

- `tool-approval`
- `ask-user`
- `pause-resume`
- `structured-output`
- `guardrails`

### 4. Orchestration and integrations

- `multi-agent`
- `handoff`
- `vision`
- `mcp`