Create an agent in TypeScript and point it at a local or remote Kestrel runtime. Start with one server-side request, inspect the terminal result, and then add streaming, memory, routes, waiting, and observability as your application needs them.
The Build journey follows the canonical kestrel profile throughout. Every guide extends the same Agent and Session model, so you keep working code at each step instead of assembling disconnected examples.
Choose a package
Use exact 0.8.5 versions throughout one integration:
| Package | Reader job |
|---|---|
@kestrel-agents/kestrel | Run the Runtime or install the CLI/TUI |
@kestrel-agents/protocol | Validate commands, events, health, and terminal results |
@kestrel-agents/sdk | Create agents and call a runner from TypeScript |
@kestrel-agents/memory | Govern authorized memory reads and persistence |
@kestrel-agents/next | Own identity and Kestrel routes in Next.js |
@kestrel-agents/ai-sdk | Map Kestrel results into AI SDK messages |
@kestrel-agents/observability | Carry trace and run correlation |
@kestrel-agents/workspace-skills | Discover and install project-owned skills |
Start building
- Build your first agent and inspect its terminal result.
- Stream the next request without changing session continuity.
- Add explicit session memory.
- Expose the agent through Next.js routes.
- Handle waiting, resume, and cancellation.
- Add observability before production operation.
Begin with Build your first agent. Run it successfully before adding the next integration capability.
Read Creating an Agent if you want the programming model before the tutorial, or browse Concepts for the complete SDK feature map.
Handle results correctly
Before shipping, read Protocol and results. A terminal result always contains assistantText: string | null; human-facing text is not inferred from structured finalized data. Use Runner events for the exact streaming vocabulary and Upgrading to 0.8 for compatibility changes.
Waiting, recovery, approval, cancellation, and failure are runtime states, not assistant prose. Keep them separate from committed output and carry correlation identifiers through every adapter.
Choose a deployment boundary
Use Local Core when the application and execution boundary belong on the same machine. Use a remote runner when a trusted service owns identity, provider access, tools, persistence, and external-effect approvals. Browsers may call an application route, but they must not supply trusted actor identity or runner credentials.