This guide is organized by the problem an application needs to solve. You do not need to enable every subsystem: start with the runtime, then add only the capabilities your agent needs.
For a first agent:
- Run the root five-minute example.
- Learn the run methods and event lifecycle in Runtime and events.
- Use Testing to make the behavior deterministic.
For a production assistant:
- Add Sessions and persistence.
- Use Multi-session management when serving more than one conversation.
- Add Context management before conversations grow large.
- Review Tool management, especially timeouts and large results.
For work that may take hours or days:
- Start with the production-assistant path.
- Use Durable goals for restart and reconnect semantics.
- Connect Scheduling and wakeups when work must start later or recur.
- Use MCP or Skills only where the task requires them.
For coordinated specialist work:
- Define bounded, isolated specialists with Subagents.
- Give each specialist only the tools and MCP servers it needs.
- Combine with Durable goals when work must survive across step boundaries.
| Guide | Covers |
|---|---|
| Runtime and events | Ask, streams, events, lifecycle, request values, HITL, queues, multimodal input |
| Sessions and persistence | Session restore/save, checkpoints, stores, concurrency, retention |
| Multi-session management | Creation, reconnect, ownership, pagination, archive, fork, and Agent lifecycle |
| Durable goals | /goal-style loops, async execution, reconnect, recovery, leases, idempotency |
| Scheduling and wakeups | Reliable integration with cron, queues, cloud schedulers, and supervisors |
| Subagents | Declarative specialists, isolation, budgets, events, nested HITL and goal integration |
| Context management | Full history versus model context, automatic compaction, ordering with reduction |
| Skills | Local SKILL.md discovery, custom backends, validation and boundaries |
| MCP | Managed transports, tool discovery, limits, authentication, reconnection and ownership |
| Tool management | Policy, aliases, hooks, repair, result reduction, dynamic tool search |
| Testing | Mock models, mock tools, streaming failures and interaction assertions |
Runnable programs live in the examples directory. Public API details also remain available through Go package documentation.
- Examples always pass a non-nil
context.Context. Usecontext.TODO()when the correct lifetime is not known yet. - Zero-value optional configurations shown as
&agentkit.SomeConfig{}are intentionally safe defaults. - “Durable” means state survives through the configured store. It does not mean a stopped process continues executing without a worker or supervisor.
- File-backed stores target one local process. Database-backed transactional implementations are required for multi-replica ownership.