Agent SDK

A lightweight, message-first agent loop with optional planning, summarization, and multi-agent orchestration. These docs walk through installation, architecture, and capability-oriented guides.

Key capabilities

• Planning mode with a structured TODO tool and strict workflow rules.
• Token-aware context summarization that archives heavy tool outputs while keeping them recoverable via get_tool_response.
• Structured output finalization powered by Zod schemas.
• Tool limits (total + parallel) with automatic finalize messaging.
• Agent composition via asTool and runtime handoffs.
• Vision-friendly message parts and provider usage normalization.
• Structured tracing (JSON) and streaming onEvent hooks.

Start here

• Getting Started – Installation, first agent, and environment setup.
• Core Concepts – State, nodes, tools, events, and planning basics.
• Architecture – Loop phases, decision heuristics, and summarization flow.

Documentation map

Foundations

• Getting Started – Install, createAgent vs createSmartAgent, and quick tours.
• Core Concepts – Mental model of state, nodes, planning, and events.
• Architecture – Detailed flow, decision factories, and design trade-offs.

API & Building Blocks

• API – Exported factories, adapters, and key option types.
• Nodes – Breakdown of resolver, agent, tools, summarization, and finalize nodes.
• Tools – Authoring tools with Zod and plugging in LangChain or MCP tools.
• Prompts – System prompt construction and planning rules.
• Structured Output – Finalize tool workflow, parsing, and recovery options.
• Guardrails – Conversation guardrails, built-in checks, and preset helpers.
• Tool Development – Advanced authoring patterns and safeguards.

Capabilities & Operations

• State Management – onStateChange hooks, snapshots, and resumable runs.
• Limits & Tokens – Token heuristics, summarization knobs, and limit trade-offs.
• Tracing – JSON trace sessions, payload capture, and sink helpers.
• Examples – Capability matrix mapped to example folders.
• FAQ – Common issues, tips, and integration notes.
• MCP Integration – Connect remote MCP servers and reuse their tool catalog.
• Tool Approvals – Human-in-the-loop gating, event payloads, and resume flow.

Example coverage

Folder	Capability	Highlights
basic	Base agent loop	Minimal tool call run with a real model.
tools	Multiple tools + events	Tavily search integration, onEvent logging.
todo-planning	Planning discipline	Enforced TODO updates with useTodoList.
tool-limit	Tool cap + finalize	Shows injected finalize system notice.
summarization	Token threshold	Demonstrates summarization triggers.
summarize-context	Summary + retrieval	Uses get_tool_response to fetch archived data.
rewrite-summary	Continue after summaries	Works with summarized history in follow-up turns.
structured-output	Schema finalize	Parses JSON into typed outputs.
multi-agent	Agent-as-tool	Delegation via agent.asTool.
handoff	Runtime handoff	Transfers control between agents.
mcp-tavily	MCP tools	Demonstrates remote MCP tool usage.
guardrails	Policy enforcement	Guardrails blocking secrets and code responses.
vision	Multimodal input	Sends text + image parts through the adapter.

Design principles

• Minimal surface – no external graph runtime; explicit while-loop orchestration.
• Developer-first – predictable events, inspection-ready state, and structured traces.
• Flexible adapters – bring any model that implements invoke; LangChain is optional.
• Observable by default – usage normalization, plan events, and Markdown traces.

Tip: open an example folder, run it locally, and then explore the related docs section for deeper background.

Use the left sidebar or search to navigate the full documentation set.