One application, different perspectives

Share structured results. Choose each agent's context.

A booking assistant and an availability specialist need the same proposed slot. They do not necessarily need the same conversation. In ADK, application state and model context are separate: agents work with a common data contract, and each agent has its own context renderers.

const app = adk({
	schema: {
		session: {
			slot: z.string().default(''),
			status: z.enum(['proposed', 'booked', 'declined']),
		},
	},
})

The app infers state types across tools, agents, steps, and renderers. Context starts empty before each model call; your renderers add instructions, selected history, and state. Keep a specialist focused, or deliberately share the wider session history.

Inspect both agents' context · Explore typed state · Compose context renderers

Control where you use AI

Choose which decisions belong to the model.

Use a model to interpret a request, reason through ambiguity, or hold a conversation. Use TypeScript to enforce a rule, select the next action, or decide what enters the model's context. You choose that balance for each part of your application.

Compose agents with steps, sequences, parallel branches, and loops. A step can execute an action directly or choose the next agent without a model call. A context renderer can select exact state fields and session events before each call. You can also let an agent choose among the tools you provide when the task needs that flexibility.

Hooks give you the same choice inside an agent's loop. A beforeModel hook can supply tool calls directly, bypassing the model while the runtime still validates arguments and executes the tools. Let other turns use the model as usual. You can make a specific action deterministic without turning the whole agent into a fixed sequence.

At Anima, this lets us put known decision rules in code and use models where interpretation is useful. An approval requirement can be a check that blocks execution, rather than an instruction we rely on the model to follow. As a workflow becomes better understood, more of its decisions can move into code while using the same state and session.

Run a deterministic check and router · Use hooks to run tools without a model call · Choose model context in code · Combine code and agent delegation

Work that continues

Wait for an answer without keeping a process alive.

A tool can ask for approval or missing information before it executes. The run returns the question, and a handler persists the session. A later request supplies the answer and continues the work, even in a different process or Lambda invocation.

You choose the persistent store and deployment. ADK records the pending work; it does not require a hosted orchestration service. The same session ledger records tool results and tracked state changes, so you can inspect how the application reached its current state.

Run the Bookings sample across two processes · Serve one turn per request

Text and voice

Keep your tools and state when the conversation becomes a call.

A voice agent can use the same booking lookup, state schema, and session ledger as a text agent. It can call text specialists during the conversation. A LiveKit handler and a supported realtime model provide the voice runtime, including speech and call lifecycle hooks.

Text agents can use OpenAI, Gemini, or Claude through provider-specific imports. Realtime voice supports OpenAI and Gemini. Change model configuration while keeping your application tools and state; provider capabilities and setup remain explicit.

Build a voice agent · Choose a model provider

Evidence from the same application

Test the code. Evaluate the conversation.

Why we build on it

Built for ongoing work at Anima.

We build clinical and operational applications where several agents contribute to the same work. They need structured information, different context, and a way to wait for people. We choose where models make decisions and where code enforces the rules. We also need to test application logic and evaluate conversations over text and voice. These requirements shape the ADK.

ADK fits TypeScript teams that want to own their application logic, runtime, and storage. Context selection controls model input; your application still owns access control. Durable pauses need a persistent store, and active voice calls need a LiveKit worker.

The package is pre-1.0. Core changes are documented in the changelog; experimental workflow and coding-agent APIs can change without a deprecation cycle. See the stability policy.

Connect your model.

Save an OpenAI API key, then run the cells in order or press Run all. Requests go directly from this browser to api.openai.com and incur provider usage. The key stays in this browser's localStorage until you clear it. The booking data is fictional; the model calls are live.

Explore the runtime without a key using the separate scripted test example.

Step 1

Define what the application remembers.

One schema types every ctx.state read and write. The tool looks up a booking and records its reference and slot. Building these definitions does not call a model.

import { adk } from '@animahealth/adk'
import { z } from 'zod'

const app = adk({
	schema: {
		session: {
			reference: z.string().default(''),
			slot: z.string().nullable().default(null),
		},
	},
})

const bookings: Record<string, string> = {
	'B-42': 'Tuesday at 14:30',
	'B-73': 'Friday at 09:00',
}
const lookupBooking = app.tool({
	name: 'lookup_booking',
	description: 'Look up an appointment by its booking reference.',
	schema: z.object({ reference: z.string() }),
	execute: (ctx) => {
		ctx.state.reference = ctx.args.reference
		ctx.state.slot = bookings[ctx.args.reference] ?? null
		return { reference: ctx.state.reference, slot: ctx.state.slot }
	},
})

lookupBooking.name

Step 2

Choose what the model sees.

The agent gets instructions, the last lookup from typed state, and conversation history. Context is rebuilt before each model call, so the next call sees state written by the tool.

import { openai } from '@animahealth/adk/openai'

const assistant = app.agent({
	name: 'booking-assistant',
	model: openai('gpt-5.6-luna'),
	context: [
		app.context.system(({ state }) =>
			'Help with booking questions. Look up references before giving appointment times. ' +
			'If the reference is missing, ask for it. A null slot means no booking was found. ' +
			`Last lookup: ${state.reference || 'none'}. Slot: ${state.slot ?? 'none'}.`,
		),
		app.context.history(),
	],
	tools: [lookupBooking],
})

assistant.name

Step 3

Let the model decide what to do.

Run this cell to make a live request. The agent should call lookup_booking for B-42 and answer with Tuesday at 14:30. Its wording can vary. Nothing in the script supplies a model response or tells the runner which tool to call.

const question = 'What time is booking B-42?'
const run = await app.run(assistant, {
	input: { message: question, initialState: { session: {} } },
})

run.output.text

Change B-42 to B-73 for a different appointment. Try B-99 for a missing booking, or “When is my appointment?” to see whether the agent asks for a reference. Each run starts a new session, so you can compare the choices without earlier conversation influencing them.

Step 4

Read the state and the tool events.

For B-42, expect reference: "B-42" and slot: "Tuesday at 14:30". Those values come from your tool. The session events show which arguments the model chose and what the tool returned. A request that needs clarification may finish without a tool call.

const outcome = {
	status: run.status,
	state: { reference: run.state.reference, slot: run.state.slot },
	tools: run.session.events.filter((event) =>
		event.type === 'tool_call' || event.type === 'tool_result',
	),
	usage: run.usage,
}

outcome

You have a live agent, structured application state, and explicit model context. The Context guide shows how to select and filter history when several agents work in one session.

Keep building.

• Install and setup to run ADK in your own project.
• Add approval and resume with the Bookings sample.
• Compose several agents with steps, sequences, and parallel branches.
• Test a workflow without model calls, or evaluate live model behavior.
• Use tools and state in a voice agent.

The vocabulary

Everything the runner executes is one of five shapes

Runnable is a union of five interfaces. Each carries a kind and a name, and the runner switches on kind — there is no sixth case and no escape hatch. The factories on your app (app.agent, app.step, app.sequence, app.parallel, app.loop) return plain objects. A runnable is data: you can build it, nest it, and pass it around before anything runs.

Any of them may hold any of them: a loop over a sequence of agents, a parallel of loops, a step that returns whichever agent the data calls for.

Step 1

A sequence of two agents, sharing one session

mockAgent(name) is an agent whose model is scripted — it lets a page like this one show composition without a key. The scripted replies are handed out in the order the model is called. So a sequence of two agents consumes two model() steps: one turn each.

import { adk, isModelEndEvent } from '@animahealth/adk'
import { mockAgent, runTest, user, model, getLastAssistantText } from '@animahealth/adk/testing'

const app = adk()

const triage = mockAgent('triage')
const reply = mockAgent('reply')

const intake = app.sequence({ name: 'intake', runnables: [triage, reply] })

const intakeRun = await runTest(intake, [
  user('My laptop will not boot.'),
  model('Category: hardware.'),
  model('Hold the power button for ten seconds, then plug in the charger.'),
])

const intakeSummary = {
  status: intakeRun.status,
  modelCalls: intakeRun.events.filter(isModelEndEvent).length,
  lastReply: getLastAssistantText(intakeRun.events),
}

intakeSummary

Two model calls, one status, and the last reply is the second agent's. Nothing was passed from triage to reply by hand. They share a session, and the second agent reads the first agent's answer out of it — which is what the next section is about.

Step 2

One ledger, and both agents are in it

A session is an append-only list of events. Print it with the agent that wrote each one and the structure of the run falls out. The sequence opens an invocation, each child agent opens its own inside it, and the model calls and replies land between the brackets.

intakeRun.events.map((e) => [e.type, e.agentName].filter(Boolean).join(' · '))

What is not there: no per-agent history, no message bus, no copy of the conversation handed from one agent to the next. There is one list. Every event carries the invocationId that produced it and the agentName that wrote it, so the nesting is recoverable from the flat list alone. Session state is computed from these events rather than stored beside them.

Step 3

A step is your code, in the same session

Put a known decision rule in a step. Here, code checks for an open ticket before calling a model, then routes the work using the session's severity. Neither decision depends on the model following an instruction.

Not every node needs a model. A step receives a context with the session, typed state, ctx.note() for annotations, ctx.output() to record the step's own output value, and the signals ctx.skip(), ctx.fail(message) and ctx.respond(text). Return a runnable from execute and the step delegates to it — that is how routing is written here.

import { isAnnotationEvent, isAssistantEvent } from '@animahealth/adk'

const escalation = mockAgent('escalation')

// A gate. `ctx.fail` ends the run; `ctx.skip` and `ctx.respond` are the other two signals.
const gate = app.step({
  name: 'gate',
  execute: (ctx) => {
    if (!ctx.state.openTicket) ctx.fail('No open ticket on this session.')
  },
})

// A router. Return a runnable and the step delegates to it — no model, no prompt.
const route = app.step({
  name: 'route',
  execute: (ctx) => {
    const authors = ctx.session.events.filter(isAssistantEvent).map((e) => e.agentName)
    ctx.note(`routing after ${authors.join(', ')}`, { kind: 'mark' })
    return ctx.state.severity === 'high' ? escalation : reply
  },
})

const desk = app.sequence({ name: 'desk', runnables: [gate, triage, route] })

const refused = await runTest(desk, [user('My laptop will not boot.')])
const refusedRun = refused.result

const escalated = await runTest(
  desk,
  [
    user('My laptop will not boot.'),
    model('Category: hardware.'),
    model('An engineer will call you back.'),
  ],
  { initialState: { session: { openTicket: true, severity: 'high' } } },
)

const stepped = {
  gateStopped: refusedRun.status,
  gateSaid: refusedRun.status === 'error' ? refusedRun.error : null,
  routedTo: escalated.events.filter(isAssistantEvent).map((e) => e.agentName),
  notes: escalated.events.filter(isAnnotationEvent).map((e) => e.message),
}

stepped

The gate failed before any model was called. The sequence stopped, and the run came back error carrying the gate's own message. With an open ticket the sequence ran triage, and the router then chose escalation over reply — a step that returns a runnable is the routing. On the way it read the ledger and appended an annotation event of its own; narrowing the union is a filter, because the package exports a type guard per event type.

Neither step called a model, so neither emitted a model_start/model_end pair. Deterministic work — parsing, gating, fetching, scoring — belongs in a step, where it costs no tokens and cannot hallucinate.

Step 4

Repeat one, or run several at once

A loop takes a single runnable, a while predicate over { iteration, lastResult, state, session }, and a required maxIterations so a bad predicate cannot run forever. A parallel takes several runnables, clones the session for each branch, runs them concurrently, and merges each branch's new events back into the parent ledger. failFast, branchTimeout, minSuccessful, and a custom merge are there when the default concatenation is not what you want.

const drafter = mockAgent('drafter')

const revise = app.loop({
  name: 'revise',
  runnable: drafter,
  maxIterations: 3,
  while: (ctx) => ctx.iteration < 3,
})

const loopRun = await runTest(revise, [
  user('Draft a subject line.'),
  model('Draft 1'),
  model('Draft 2'),
  model('Draft 3'),
])

const sentiment = mockAgent('sentiment')
const wordcount = mockAgent('wordcount')

const analysis = app.parallel({ name: 'analysis', runnables: [sentiment, wordcount] })

const fanRun = await runTest(analysis, [
  user('Two reviews came in.'),
  model('positive'),
  model('nine words'),
])

const branching = {
  drafts: loopRun.events.filter(isAssistantEvent).map((e) => e.text),
  branches: fanRun.events.filter(isAssistantEvent).map((e) => `${e.agentName}: ${e.text}`),
}

branching

Three iterations, three drafts, one session. Two branches, two replies, still one session — the branch sessions are clones, and only the events they produced come back. The merge goes into the same append-only list, so a parallel is not a special result type you have to unpack. Whatever the branches did is in the ledger afterwards.

Step 5

The ledger is history — the prompt is rendered from it

An agent's context is an array of renderers applied in order. The render context they receive starts with an empty event list. Nothing reaches the model until a renderer puts it there. app.context.system(…) adds an instruction, and app.context.history() pulls events out of the ledger — its scope decides which ones. This runs again before every model call. Put a recorder of your own in the array and you can watch it happen.

import { openai } from '@animahealth/adk/openai'

const rendered: { at: string; sees: string[] }[] = []
const recordAs = (at: string) =>
  app.context((ctx) => {
    rendered.push({ at, sees: ctx.events.map((e) => e.type) })
    return ctx
  })

const scribe = app.agent({
  name: 'scribe',
  model: openai('gpt-5.6-luna'),
  context: [
    recordAs('renderers start'),
    app.context.system('Answer in one sentence.'),
    app.context.history(),
    recordAs('history added'),
  ],
})

const twice = app.loop({
  name: 'twice',
  runnable: scribe,
  maxIterations: 2,
  while: (ctx) => ctx.iteration < 2,
})

const scribeRun = await runTest(twice, [
  user('What is the ledger for?'),
  model('It is the append-only history of everything that happened.'),
  model('Every runnable in the program writes to it.'),
])

const seam = { renderedPerModelCall: rendered, ledgerLength: scribeRun.events.length }

seam

Four entries, two per model call: empty at the start of the renderer chain, populated after history(). The second call's context contains the first call's reply, because by then it was in the ledger. The agent's model config never changed; the input to it was rebuilt from scratch, twice.

The ledger records what happened in full, and the prompt is a projection of it chosen per agent and per turn — a renderer decision, taken apart in Context: what the model sees. What that ledger buys you once it is persisted belongs to Sessions and state.

Step 1

Install the package

In your project directory, install the ADK and Zod.

mkdir my-agent
cd my-agent
npm init -y

npm install @animahealth/adk zod@^3.25
npm install -D tsx

tsx runs the TypeScript file below. If your project already runs TypeScript, use your existing runner.

Step 2

Create an agent

Save this as agent.mts.

import { adk } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'

const app = adk()

const assistant = app.agent({
	name: 'assistant',
	model: openai('gpt-5.6-luna'),
	context: [
		app.context.system('Answer concisely.'),
		app.context.history(),
	],
})

const run = await app.run(assistant, 'Suggest a name for a booking assistant.')
console.log(run.output.text)

The .mts extension lets you use top-level await without changing your project's module configuration.

Step 3

Set your key and run

In your terminal, replace the placeholder with your OpenAI API key.

export OPENAI_API_KEY="your-api-key"
npx tsx agent.mts

The agent calls OpenAI and prints its suggestion in your terminal. The wording varies with each run. To use another provider, see Models and providers.

Build on it

Setup is complete. Add tools and typed state with the Quickstart.

When your application needs more, follow the relevant guide.

• Test your agents
• Add web search and page fetching
• Serve an agent over HTTP
• Add a terminal interface

Your key

Paste a key, run everything

This site is static — no backend, no proxy. Your key lives in this browser's localStorage and requests go straight to api.openai.com, as they would from your own machine.

Step 1

An agent with a tool

The whole program: one tool with a Zod schema, one agent that carries it, one run. The model reads the tool's description and decides to call it. Your execute computes the answer in this page. This is the same code you would run locally after npm install @animahealth/adk. Building costs nothing and needs no key: this cell prints the agent's name.

import { adk } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'
import { z } from 'zod'

const app = adk()

const calculator = app.tool({
  name: 'calculate',
  description: 'Evaluate a mathematical expression',
  schema: z.object({ expression: z.string() }),
  execute: (ctx) => {
    const sanitized = ctx.args.expression.replace(/[^\d\s+*/().-]/g, '')
    return { result: Function(`"use strict"; return (${sanitized})`)() }
  },
})

const assistant = app.agent({
  name: 'math_assistant',
  model: openai('gpt-5.6-luna'),
  context: [app.context.system('Use the calculator for arithmetic.'), app.context.history()],
  tools: [calculator],
})

assistant.name

Now run it. The model chooses to call the calculator, and your code does the arithmetic. What prints is one short assistant sentence carrying the computed number. Edit the question and run again.

const run = await app.run(assistant, 'What is 731 * 268, minus 17?')

run.output.text

Step 2

What it cost

Nothing about a run is opaque. Tokens, model calls, and cost come straight off the run's model_end events. This cell reads the run bound in step 1, so that cell has to have been pressed, with a key. It prints a usage object: input and output token counts, two model calls, and an estimated cost.

run.usage

Step 3

The ledger the run left behind

Everything the agent did is an append-only event history. It belongs to the session, not to the run: a run is one pass over it. So the ledger is run.session.events, and it accumulates across every run on that session. run.usage is scoped the same way: run a second time on the same session and its result reports both runs' cost. This cell reads the same run from step 1. The tool_call and tool_result pair: the model decided, your code executed. Each model_start/model_end pair brackets one model call. A tool-using turn makes two round-trips — one to decide the call, one to answer with its result — which is why run.usage reports two model calls. On a reasoning model, the summary lands as a thought event.

run.session.events.map((event) => event.type)

Aside

Testing the same agent, no key

The test kit replaces only the model with scripted turns. The tool still executes and the ledger still accrues. So agent tests run deterministically in CI, with no credentials. This cell needs the build cell from step 1 pressed once, and no key. It prints the tool results the scripted run produced. Skip it if you only came to build.

import { getToolResults, runTest, user, model } from '@animahealth/adk/testing'

// The assistant from step 1, with the model's turns scripted: the script decides THAT the
// calculator is called; the calculator itself really runs.
const test = await runTest(assistant, [
  user('What is 134 divided by 4?'),
  model({ toolCalls: [{ name: 'calculate', args: { expression: '134 / 4' } }] }),
  model('134 divided by 4 is 33.5.'),
])

getToolResults(test.events)

Where to go next

Three doors out of here

Every chapter behind this one teaches the same way: by running the code.

• Get it on your machine. Install and setup moves this program into your editor, recipe by recipe.
• See an agent stop and ask a human. The Bookings sample pauses mid-run and resumes from a stored session.
• Understand what you just ran. Five primitives and one ledger names every shape the runner executes.

Step 1

A model is a value

openai(name, options?) returns an object, not a client. It holds provider, name, and whatever options you passed — nothing else you can see. The adapter that will eventually make the HTTP call rides along on a non-enumerable symbol, so a descriptor stays inspectable, comparable and safe to store.

The first three cells below run with no key. The two live cells further down call OpenAI directly from this page, so paste a key when you get there.

import { adk } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'

const app = adk()

// Two descriptors. No network, no client, no key — just data.
const luna = openai('gpt-5.6-luna')
const tuned = openai('gpt-5.6-terra', { temperature: 0.2, maxTokens: 300 })
const descriptors = { luna, tuned }

descriptors

Every provider factory takes the same shape: a model name, then an options object typed for that provider. temperature and maxTokens are the two options all three share; everything else is provider-specific and covered in step 3. The factories also carry a realtime variant (openai.realtime, gemini.realtime) that wraps a descriptor for voice — that wrapper belongs to the voice runtime, not to this chapter.

Step 2

Descriptor, adapter, runner

A descriptor names a model; an adapter is the thing that speaks the provider's wire protocol. The runner picks one per model call, in a fixed order. An adapter registered on the app — adk({ adapters: { openai: myAdapter } }) — wins outright. Otherwise the runner uses the factory the descriptor carries, which is what importing @animahealth/adk/openai attaches. Failing both, it imports the provider's adapter dynamically; a provider it has no case for throws, naming the subpath you should have imported.

The order is what makes the swap possible. Below, runTest registers a scripted adapter, so the descriptor still says which model this agent is for while no provider client is ever built and nothing reaches the network.

import { runTest, user, model, getLastAssistantText } from '@animahealth/adk/testing'

const triage = app.agent({
  name: 'triage',
  model: luna,
  context: [app.context.system('Answer in one short sentence.'), app.context.history()],
})

const scriptedOpenAI = await runTest(triage, [user('Ping'), model('Pong, from a scripted turn.')])

getLastAssistantText(scriptedOpenAI.events)

Now point the same agent at a different provider. A descriptor is plain data, so you can write one out by hand instead of calling a factory — useful when the model comes from configuration. This agent names Gemini, and it runs the same way the OpenAI one did, because runTest registers its scripted adapter for both providers.

const triageOnGemini = app.agent({
  name: 'triage_gemini',
  model: { provider: 'gemini', name: 'gemini-3-flash' },
  context: [app.context.system('Answer in one short sentence.'), app.context.history()],
})

const scriptedGemini = await runTest(triageOnGemini, [user('Ping'), model('Pong, again.')])
const swapped = {
  named: triageOnGemini.model,
  reply: getLastAssistantText(scriptedGemini.events),
}

swapped

One limit to watch for: runTest registers its scripted adapter for openai and gemini only. An agent whose descriptor says claude falls through to the real Vertex adapter and will ask for Google credentials. Pass your own adapter through adk({ adapters: { claude: … } }) for that case.

This page is itself an instance of rule one. The adk() it serves has an OpenAI adapter registered on it — one that reads the key from the box above at call time, and sets the browser flag from step 4. Your openai(…) descriptors are honoured for which model to call; the registered adapter decides how.

Step 3

Options that change the call

Provider options live on the descriptor, so changing one is a one-line edit with no plumbing behind it. OpenAI takes reasoning: { effort, summary? }; effort is minimal, low, medium or high. Run this, then change the effort and run it again — reasoningTokens moves, and so does the cost.

One rule to know: when a descriptor carries reasoning, the adapter does not send temperature at all, because reasoning models reject a non-default value. Setting both is not an error; the temperature is dropped.

const scout = app.agent({
  name: 'scout',
  model: openai('gpt-5.6-luna', { reasoning: { effort: 'minimal' } }),
  context: [app.context.system('Answer in one short sentence.'), app.context.history()],
})

const scouted = await app.run(scout, 'Why is the sky blue?')

scouted.usage

The modelName in that summary is the name you wrote, not whatever the endpoint resolved it to, and the cost estimate is looked up from it. That matters in step 4, where a deployment can be called something else.

Gemini and Claude take their own thinking controls. Their SDKs are optional peers behind @animahealth/adk/gemini and @animahealth/adk/claude, which this page does not serve — so these two are static, checked against the same types the cells above compile against.

import { gemini } from '@animahealth/adk/gemini'
import { claude } from '@animahealth/adk/claude'

// Gemini: a thinking budget in tokens, or a level; thoughts can be returned.
const flash = gemini('gemini-3-flash', {
  temperature: 0.3,
  thinkingConfig: { thinkingLevel: 'low', includeThoughts: true },
})

// Claude runs through Google Vertex, so `vertex` is required — there is no second argument
// without it. Credentials fall back to GOOGLE_APPLICATION_CREDENTIALS when the path is omitted.
const sonnet = claude('claude-sonnet-4-20250514', {
  vertex: { project: 'my-project', location: 'us-east5' },
  thinking: { budgetTokens: 4000 },
})

All three providers also accept retry on the descriptor, applied around the model stream. It takes the same RetryConfig as a tool's — see Tools.

Step 4

Endpoints, Azure and the browser

Where the call goes is the adapter's business, not the descriptor's. The OpenAI adapter takes an ordered list of endpoints and tries them in turn, falling forward only on failures worth retrying elsewhere: rate limits, timeouts, connection errors, 500/502/503, and a missing model or deployment. Any other error is thrown from the first endpoint that raises it.

import { adk } from '@animahealth/adk'
import { OpenAIAdapter } from '@animahealth/adk/openai'

const openAIAdapter = new OpenAIAdapter([
  {
    type: 'azure',
    baseUrl: 'https://my-resource.openai.azure.com',
    apiVersion: '2025-01-01-preview',
    apiKey: process.env.AZURE_OPENAI_API_KEY,
    // The name your code writes, mapped to the name your Azure resource deploys it under.
    modelMapping: { 'gpt-5.6-luna': 'gpt-5-6-luna-2026-04' },
  },
  // Second choice: OpenAI's EU region, by base URL. Any OpenAI-compatible host works here.
  { type: 'openai', baseUrl: 'https://eu.api.openai.com/v1', apiKey: process.env.OPENAI_EU_API_KEY },
  // Last: plain api.openai.com.
  { type: 'openai', apiKey: process.env.OPENAI_API_KEY },
])

const configuredApp = adk({ adapters: { openai: openAIAdapter } })

For an azure endpoint the adapter builds the client against {baseUrl}/openai/deployments/{deployment} with your apiVersion; modelMapping is what turns the logical name on the descriptor into that deployment. Usage and cost still report the logical name, so the accounting does not change when you move a model behind an alias.

Pass no endpoints and the adapter builds the list from the environment, in this order: AZURE_OPENAI_ENDPOINT with AZURE_OPENAI_API_KEY, then OPENAI_EU_API_KEY, then OPENAI_API_KEY. With none of them set it throws, naming all three.

The last endpoint field is a safety catch. The OpenAI client refuses to run in a browser, because the usual reason it is there is a server key baked into shipped JavaScript. dangerouslyAllowBrowser: true opts out of that guard, for the case it was meant to allow: the end user typed the key themselves. This page is that case — it is how the cells above reach api.openai.com with no backend in between. Never set it with a key your user did not type.

// A page where the reader supplies the key, as this one does: `keyTheReaderTyped` came from an
// input on the page, never from a build-time constant.
const browserAdapter = new OpenAIAdapter([
  { type: 'openai', apiKey: keyTheReaderTyped, dangerouslyAllowBrowser: true },
])

The other two providers put their connection on the descriptor instead of on an endpoint list: Gemini takes an optional vertex: { project, location, credentials? } (or an API key given to new GeminiAdapter({ apiKey })), and Claude requires vertex, as step 3 showed.

Step 5

Prompt caching

Caching is opt-in per descriptor, and the two providers spell it differently because their APIs do. OpenAI supports explicit breakpoints only: give a stable key (1 to 64 characters — the adapter throws outside that), the mode explicit, and the 30m sliding window that refreshes on reuse.

The key alone does nothing. Some context message must also be tagged as cacheable, marking where the reusable prefix ends. app.context.cacheableUser(text) is that tag; if nothing in the rendered context carries it, the adapter throws rather than quietly paying full price.

const briefer = app.agent({
  name: 'briefer',
  model: openai('gpt-5.6-luna', {
    promptCache: { key: 'clinic-handbook-v3', mode: 'explicit', ttl: '30m' },
  }),
  context: [
    app.context.system('You answer questions about the handbook.'),
    // The long, stable prefix — everything before this point is the cacheable span.
    app.context.cacheableUser(handbookText),
    app.context.history(),
  ],
})

Claude's caching is on by default for Vertex models and is configured by disabling or tuning it: enabled, a ttl of 5m or 1h, and system choosing whether all system blocks are cacheable or only tagged ones. A 1h cache write costs more than a 5m one.

const cachedSonnet = claude('claude-sonnet-4-20250514', {
  vertex: { project: 'my-project', location: 'us-east5' },
  promptCache: { enabled: true, ttl: '1h', system: 'tagged' },
})

Either way, the result shows up in the run's usage as totalCachedTokens and totalCacheWriteTokens, priced separately from fresh input.

Step 6

Images and audio going in

Multimodal input is not a model option — it is a property of the message. A user message carries media, a list of parts, each an image, audio or document with a source that is either base64 with a mimeType, or a url. The adapter for whichever provider you named translates the parts.

This is live, and it needs a model that can see. The image below is a 32-pixel square inlined as base64 — swap the data or the question and run it again.

const redSquarePng =
  'iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAIAAAD8GO2jAAAAKklEQVR42mO4o6ZGU8QwasGoBaMWjFowasGoBaMWjFowasGoBaMWDBULAIjyoD2JhwFtAAAAAElFTkSuQmCC'

const looker = app.agent({
  name: 'looker',
  model: openai('gpt-5.6-luna'),
  context: [app.context.system('Answer with one word.'), app.context.history()],
})

const seen = await app.run(looker, {
  input: {
    message: {
      text: 'What colour is this square?',
      media: [
        {
          type: 'image',
          source: { type: 'base64', mimeType: 'image/png', data: redSquarePng },
        },
      ],
    },
  },
})

seen.output.text

Coverage is per adapter and per position, and it is not uniform. On a user message, image reaches all three providers and audio reaches OpenAI and Gemini; Claude's user serializer has no audio branch. document parts are dropped from a user message by all three — they are serialized only when they arrive on a tool result, and then only for Gemini and Claude. Nothing throws when a part is dropped, so check the part type against the provider you are calling.

A descriptor names who answers; the adapter decides how the call is made. The other half of an agent's config — what it can do — is Tools, the next chapter.

Step 1

The whole config, in one object

app.tool takes one object and returns a tool. Three fields are the contract the model sees — name, description, schema — and execute is the work. The rest are optional and covered below. Every cell here but the last runs with no key: the model's turns are scripted and the tools themselves really execute. The last cell asks a real model to choose, so paste a key if you want it — it stays in this browser.

import { adk } from '@animahealth/adk'
import { z } from 'zod'

const app = adk()

const WAREHOUSE: Record<string, number> = { 'ADK-1': 12, 'ADK-2': 0 }

const checkStock = app.tool({
  name: 'check_stock',
  description: 'Look up how many units of a SKU the warehouse holds',
  schema: z.object({
    sku: z.string().describe('Warehouse SKU, e.g. ADK-1'),
    quantity: z.number().int().positive().describe('Units the customer wants'),
  }),
  execute: (ctx) => {
    const onHand = WAREHOUSE[ctx.args.sku] ?? 0
    return { sku: ctx.args.sku, onHand, canFulfil: onHand >= ctx.args.quantity }
  },
})

// Every key app.tool reads. There is no tenth.
Object.keys(checkStock)

name and description are prompt: they are the only reason the model reaches for this tool rather than another, so write the description for a reader who cannot see your code. schema is a Zod schema — it becomes the JSON Schema the provider is given, so .describe() on a field is prompt too. yieldSchema belongs to tools that stop and ask a human, at the end of this page. app.tool throws at build time if a config has neither execute nor yieldSchema: a tool that can do nothing is a mistake, not a runtime surprise. Everything here is a function tool: besides these and MCP servers, an agent's tools may hold a provider tool such as { type: 'web_search' }, which runs inside the model provider and has no execute of yours.

Step 2

The schema is the border, not a suggestion

Arguments arrive as JSON a language model wrote, so they are wrong often enough to design for. Each call is coerced toward the schema first — a stringy number becomes a number — and then parsed by Zod. execute only ever sees arguments that parsed. When they do not parse, the run does not throw: the call becomes a tool_result whose error reads Invalid arguments: …, the model reads it on the next round-trip, and it can correct itself.

Three calls below: one clean, one where quantity arrives as the string '5', one missing quantity. Only the third is an error, and the agent survives it.

import { openai } from '@animahealth/adk/openai'
import { runTest, user, model, findEventsByType } from '@animahealth/adk/testing'

const shopkeeper = app.agent({
  name: 'shopkeeper',
  model: openai('gpt-5.6-luna'),
  context: [app.context.system('Check stock before promising anything.'), app.context.history()],
  tools: [checkStock],
})

const stockRun = await runTest(shopkeeper, [
  user('Can I have 3 of ADK-1 and 5 of ADK-2?'),
  model({ toolCalls: [{ name: 'check_stock', args: { sku: 'ADK-1', quantity: 3 } }] }),
  model({ toolCalls: [{ name: 'check_stock', args: { sku: 'ADK-2', quantity: '5' } }] }),
  model({ toolCalls: [{ name: 'check_stock', args: { sku: 'ADK-1' } }] }),
  model('ADK-1 has 12 on hand; ADK-2 is out of stock.'),
])

findEventsByType(stockRun.events, 'tool_result').map((event) =>
  event.error
    ? { name: event.name, error: `${event.error.slice(0, 44)}…` }
    : { name: event.name, result: event.result },
)

Section 5 shows the same mechanism catching an exception your own code threw.

Step 3

What ctx carries

execute takes one argument. ctx.args is the parsed input, and the rest of the context is the run around it: toolName and callId identify this call, invocationId and runnable identify the turn and the agent, session is the ledger, state reads and writes it, and signal is the run's AbortSignal to pass to your own fetch. Rather than list them, ask the context itself.

const inspect = app.tool({
  name: 'inspect_context',
  description: 'Report what a tool can see while it runs',
  schema: z.object({ note: z.string() }),
  execute: (ctx) => {
    // State writes are events too: this lands on the session ledger, not on a local variable.
    ctx.state.update({ lastNote: ctx.args.note })
    return {
      carries: Object.keys(ctx).sort(),
      toolName: ctx.toolName,
      agent: ctx.runnable.name,
      session: ctx.session.id,
      aborted: ctx.signal?.aborted ?? false,
      lastNote: ctx.state.lastNote,
    }
  },
})

const inspector = app.agent({
  name: 'inspector',
  model: openai('gpt-5.6-luna'),
  context: [app.context.history()],
  tools: [inspect],
})

const inspectRun = await runTest(inspector, [
  user('Write down that the shelf is dusty.'),
  model({ toolCalls: [{ name: 'inspect_context', args: { note: 'shelf is dusty' } }] }),
  model('Noted.'),
])

findEventsByType(inspectRun.events, 'tool_result')[0]?.result

Four of those keys — output, run, spawn, and dispatch — change the shape of the run rather than just answering it, and they belong to Many agents. (call in that list is the former name of run, kept deprecated — use run.)

Step 4

prepare and finalize: the two optional halves

prepare runs after the arguments parse and before execute. Return a value and it replaces the arguments execute will see; return nothing and they pass through. It is where normalisation, defaulting, and authorization lookups belong, so execute can be about the work.

finalize runs after execute returns, with the output on ctx.result. Return a value and it replaces the result the model is shown; return nothing and the output stands. Redaction, truncation, and logging belong here. It runs only on a plain return — a control signal such as ctx.output(), or a thrown error, skips it.

type Booking = { room: string; minutes: number; reference: string }

const trace: string[] = []

const bookRoom = app.tool({
  name: 'book_room',
  description: 'Reserve a meeting room for a number of minutes',
  schema: z.object({ room: z.string(), minutes: z.number() }),
  prepare: (ctx) => {
    trace.push(`prepare(${JSON.stringify(ctx.args)})`)
    // Normalise once, here — execute never has to wonder about casing or absurd durations.
    return { room: ctx.args.room.trim().toUpperCase(), minutes: Math.min(ctx.args.minutes, 60) }
  },
  execute: (ctx): Booking => {
    trace.push(`execute(${JSON.stringify(ctx.args)})`)
    return { room: ctx.args.room, minutes: ctx.args.minutes, reference: 'REF-8891-KLM' }
  },
  finalize: (ctx): Booking => {
    trace.push(`finalize(${String(ctx.result?.reference)})`)
    // The model gets a booking it can talk about, not the reference it could leak.
    return { room: ctx.result!.room, minutes: ctx.result!.minutes, reference: 'REF-•••' }
  },
})

const receptionist = app.agent({
  name: 'receptionist',
  model: openai('gpt-5.6-luna'),
  context: [app.context.history()],
  tools: [bookRoom],
})

const bookingRun = await runTest(receptionist, [
  user('Book me  orion  for four hours.'),
  model({ toolCalls: [{ name: 'book_room', args: { room: '  orion  ', minutes: 240 } }] }),
  model('Booked ORION for 60 minutes.'),
])

const lifecycle = {
  trace,
  modelSaw: findEventsByType(bookingRun.events, 'tool_result')[0]?.result,
}

lifecycle

Read the trace top to bottom: the model asked for ' orion ' and 240 minutes, prepare handed execute 'ORION' and 60, and the model was told a reference that is not the real one. Three functions, one call, and the only thing the model ever learns is what finalize allowed.

Step 5

Timeouts, retries, and what the model is told

Two optional fields make a tool survivable, and one rule decides what the model hears.

• retry is a RetryConfig: { maxAttempts, initialDelayMs, maxDelayMs, backoffMultiplier }, plus an optional retryableErrors(error) predicate that bails out of retrying the errors it rejects. It re-runs execute with randomized exponential backoff. The retries are internal — the session ledger gets one tool_result for the call, not one per attempt.
• timeout is milliseconds, and it wraps the retrying execution as a whole — it is a budget for the call, not for one attempt. On expiry the result event carries timedOut: true and an error naming the tool and the budget.
• An exception out of execute becomes that same result event, with error set to its message. It is not swallowed and it is not thrown at your app.run: it is handed to the model as the outcome of the call, which is the only place that can do something about it. Whatever your error message says, the model reads. Guardrails covers what a throw does in full.

One agent, three tools, three failures — a flaky call that recovers on its third attempt, a slow call that blows a 25ms budget, and a call that throws.

let upstreamCalls = 0

const fetchRate = app.tool({
  name: 'fetch_rate',
  description: 'Fetch a currency exchange rate from the upstream feed',
  schema: z.object({ pair: z.string() }),
  retry: { maxAttempts: 3, initialDelayMs: 1, maxDelayMs: 8, backoffMultiplier: 2 },
  execute: async (ctx) => {
    upstreamCalls++
    if (upstreamCalls < 3) throw new Error(`upstream 503 (attempt ${upstreamCalls})`)
    return { pair: ctx.args.pair, rate: 1.27, attempts: upstreamCalls }
  },
})

const slowReport = app.tool({
  name: 'slow_report',
  description: 'Build the quarterly report',
  schema: z.object({}),
  timeout: 25,
  execute: async (): Promise<{ report: string }> => {
    await new Promise((resolve) => setTimeout(resolve, 400))
    return { report: 'never arrives' }
  },
})

const chargeCard = app.tool({
  name: 'charge_card',
  description: 'Charge the customer their balance',
  schema: z.object({ amount: z.number() }),
  execute: (ctx): { charged: number } => {
    // Say something the model can act on: it is the audience for this string.
    throw new Error(`Card declined for ${ctx.args.amount} — ask for another payment method`)
  },
})

const teller = app.agent({
  name: 'teller',
  model: openai('gpt-5.6-luna'),
  context: [app.context.history()],
  tools: [fetchRate, slowReport, chargeCard],
})

const failureRun = await runTest(teller, [
  user('Get me the GBPUSD rate, run the report, and charge 40.'),
  model({ toolCalls: [{ name: 'fetch_rate', args: { pair: 'GBPUSD' } }] }),
  model({ toolCalls: [{ name: 'slow_report', args: {} }] }),
  model({ toolCalls: [{ name: 'charge_card', args: { amount: 40 } }] }),
  model('Rate is 1.27. The report timed out and the card was declined.'),
])

findEventsByType(failureRun.events, 'tool_result').map((event) => ({
  name: event.name,
  result: event.result,
  error: event.error,
  timedOut: event.timedOut,
}))

fetch_rate reports attempts: 3 — proof that retry re-ran execute, and that only the surviving attempt reached the ledger. The other two failed, the run did not, and the agent still produced its answer. That is the whole failure contract: a tool can fail, and the model finds out.

Step 6

A real model choosing between two tools

Everything above scripted the decision so the tools could be exercised without a key. The decision itself is the model's, and it is made from the names and descriptions alone. Paste a key in the box at the top, then run this: two tools, one question that only one of them answers. Change the question and watch the choice change.

const ZONES: Record<string, string> = { Tokyo: 'Asia/Tokyo', London: 'Europe/London' }

const localTime = app.tool({
  name: 'local_time',
  description: 'Get the current wall-clock time in a named city',
  schema: z.object({ city: z.string().describe('City name, e.g. Tokyo') }),
  execute: (ctx) => {
    const zone = ZONES[ctx.args.city]
    if (!zone) throw new Error(`No timezone on file for ${ctx.args.city} — try Tokyo or London`)
    return { city: ctx.args.city, time: new Date().toLocaleTimeString('en-GB', { timeZone: zone }) }
  },
})

const currentWeather = app.tool({
  name: 'current_weather',
  description: 'Get the current temperature and conditions in a named city',
  schema: z.object({ city: z.string().describe('City name, e.g. Tokyo') }),
  // A stub, so the cell needs no second API key: only the description above decides whether the
  // model reaches for this tool or the one beside it.
  execute: (ctx) => ({ city: ctx.args.city, celsius: 19, conditions: 'light rain' }),
})

const concierge = app.agent({
  name: 'concierge',
  model: openai('gpt-5.6-luna'),
  context: [
    app.context.system('Answer with the tools. Never guess a time or a temperature.'),
    app.context.history(),
  ],
  tools: [localTime, currentWeather],
})

const conciergeRun = await app.run(concierge, 'What time is it in Tokyo right now?')

const chosen = {
  called: findEventsByType(conciergeRun.session.events, 'tool_call').map((event) => event.name),
  answer: conciergeRun.output.text,
}

chosen

The only thing separating the two tools is a sentence each: the description is what decides whether your tool gets called.

Next

Tools that stop and ask

A tool with a yieldSchema and no execute computes nothing. It suspends the run, and the agent sleeps as a database row until a human supplies the answer. That is Stopping to ask.

Step 1

A context is a pipeline of renderers

A context renderer takes a RenderContext and returns one. The agent's context array is applied in order, each renderer seeing what the previous one produced. app.context.system(…) appends a system event; app.context.history() appends the session's events; a filter drops some again. Because a renderer is an ordinary function, one that returns its input unchanged is a tap — a way to see the finished render. Every cell below uses one.

import { adk, type Agent } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'
import { z } from 'zod'

const app = adk()

// One entry per model call, in the order the calls happen.
const renders: Array<{ messages: string[]; tools: string[] }> = []

// A renderer that changes nothing and records everything: the exact list the provider is about
// to serialize. `app.context(fn)` is the escape hatch — raw RenderContext in, RenderContext out.
const tap = app.context((ctx) => {
  renders.push({
    messages: ctx.events.flatMap((e) =>
      e.type === 'system' || e.type === 'user' || e.type === 'assistant' || e.type === 'thought'
        ? [`${e.type}: ${e.text}`]
        : e.type === 'tool_call'
          ? [`tool_call: ${e.name}(${JSON.stringify(e.args)})`]
          : e.type === 'tool_result'
            ? [`tool_result: ${JSON.stringify(e.result)}`]
            : [],
    ),
    tools: ctx.functionTools.map((tool) => tool.name),
  })
  return ctx
})

const allergies = app.tool({
  name: 'lookup_allergies',
  description: 'Look up the recorded allergies for a patient',
  schema: z.object({ patient: z.string() }),
  execute: (ctx) => ({ patient: ctx.args.patient, allergies: ['penicillin'] }),
})

const triage = app.agent({
  name: 'triage',
  model: openai('gpt-5.6-luna'),
  context: [
    app.context.system('You are a triage nurse. Check the allergy record before advising.'),
    app.context.history(),
    tap,
  ],
  tools: [allergies],
})

triage.context.length

Three renderers, and the tap is the last one, so it sees the final result. Drop app.context.history() from that array and the agent sees no conversation at all — the session would still be recording every word. Nothing reaches the model except through this list.

Step 2

The ledger is stored; the context is rendered

The session ledger is append-only and permanent. The context is neither — it is rebuilt from scratch before every model call, so a tool-using turn renders twice. Run the same agent with a scripted model and compare the three things below: what accrued in the ledger, what the two renders contained, and what each model_start event recorded.

import { isModelStartEvent } from '@animahealth/adk'
import { runTest, user, model } from '@animahealth/adk/testing'

renders.length = 0 // so this cell prints this run, however many times you press Run

const consult = await runTest(triage, [
  user('Can I take amoxicillin?'),
  model({
    thought: 'Check the record first.',
    toolCalls: [{ name: 'lookup_allergies', args: { patient: 'ada' } }],
  }),
  model('Your record lists penicillin, and amoxicillin is a penicillin. Avoid it.'),
])

const seam = {
  ledger: consult.events.map((e) => e.type),
  modelStarts: consult.events.filter(isModelStartEvent).map((e) => ({
    step: e.stepIndex,
    messageCount: e.messageCount,
    tools: e.tools.map((t) => t.name),
  })),
  firstRender: renders[0],
  secondRender: renders[1],
}

seam

The first render is the system message and the question. The second render is that plus the thought, the tool call, and the tool's real result — the model gets its own decision back as input, which is how a tool-using turn resolves. Neither render is stored anywhere; both were derived from the ledger and thrown away.

app.context.history() copies the session slice whole, bookkeeping events included. Only message-shaped events — system, user, assistant, thought, tool_call, tool_result — are serialized into a prompt, and messageCount counts exactly those. That is why the ledger list above is longer than the message counts beside it.

Step 3

Scopes and filters: paying for less

history() takes a scope that decides which invocations are visible — it matters once an agent hands off to another. Filters then run after history and shrink what it produced, so order in the array decides the outcome: pruneReasoning() before history() would prune an empty list.

Now the filters. This agent prunes reasoning and keeps only the two most recent prompt events. Watch what falls out of the window on the second call.

const terse: string[][] = []

const briefTriage = app.agent({
  name: 'brief_triage',
  model: openai('gpt-5.6-luna'),
  context: [
    app.context.system('Be brief.'),
    app.context.history(),
    app.context.pruneReasoning(),
    app.context.selectRecent(2),
    app.context((ctx) => {
      terse.push(ctx.events.map((e) => e.type))
      return ctx
    }),
  ],
  tools: [allergies],
})

const trimmed = await runTest(briefTriage, [
  user('Can I take amoxicillin?'),
  model({
    thought: 'Check the record first.',
    toolCalls: [{ name: 'lookup_allergies', args: { patient: 'ada' } }],
  }),
  model('Avoid it.'),
])

const filtered = { ledger: trimmed.events.map((e) => e.type), rendered: terse }

filtered

On the second call the user's question has fallen out of the window and the model is answering from a tool result alone. That is the cost of a small selectRecent, and it is why the filter counts only prompt events and re-attaches a tool_call whose tool_result survived the cut — a result without its call is a request providers reject. It also lifts system events to the front, so instructions are never what gets trimmed.

Step 4

Which tools the model may pick, this turn

Tools belong to the agent, but availability is per-render. limitTools(names) sets allowedTools on the context and toolChoice(choice) overrides the agent's default — both for this call only, and both are ordinary renderers, so they can be conditional on state.

const gates: Array<{ tools: string[]; allowedTools: string[]; toolChoice: string }> = []

const escalate = app.tool({
  name: 'escalate_to_gp',
  description: 'Escalate the question to a GP',
  schema: z.object({ reason: z.string() }),
  execute: (ctx) => ({ escalated: true, reason: ctx.args.reason }),
})

const gatedTriage = app.agent({
  name: 'gated_triage',
  model: openai('gpt-5.6-luna'),
  context: [
    app.context.system('Look up the allergy record before doing anything else.'),
    app.context.history(),
    app.context.limitTools(['lookup_allergies']),
    app.context.toolChoice('required'),
    app.context((ctx) => {
      gates.push({
        tools: ctx.functionTools.map((t) => t.name),
        allowedTools: [...(ctx.allowedTools ?? [])],
        toolChoice: JSON.stringify(ctx.toolChoice),
      })
      return ctx
    }),
  ],
  tools: [allergies, escalate],
})

const gatedRun = await runTest(gatedTriage, [
  user('Can I take amoxicillin?'),
  model({ toolCalls: [{ name: 'lookup_allergies', args: { patient: 'ada' } }] }),
  model('Avoid it.'),
])

const gateView = {
  rendered: gates[0],
  modelStartTools: gatedRun.events.filter(isModelStartEvent).map((e) => e.tools.map((t) => t.name)),
}

gateView

Read that result carefully. Both tool definitions are still in functionTools, and both still appear in model_start. limitTools does not delete a tool — it narrows the choice. The OpenAI adapter turns allowedTools into a tool_choice of type allowed_tools, folding in toolChoice as the mode:

// what serializeToolChoice(ctx.toolChoice, ctx.allowedTools) produces for the render above
{
  "type": "allowed_tools",
  "mode": "required",
  "tools": [{ "type": "function", "name": "lookup_allergies" }]
}

Other adapters express the same constraint in their own dialect. If you need a tool to be invisible — absent from the token count as well as the choice — leave it off the agent, or give the agent a narrower peer.

Step 5

Typed prompt fragments

Pass a function instead of a string to system or user and it is rendered per call against the app's state schema. The argument carries state, typed from that schema — session keys are readable at the top level and by scope — and outputSchema, the agent's output type already rendered as text you can drop into a prompt. A typo in a state key is a compile error, not a blank in a prompt.

const clinic = adk({
  schema: {
    session: {
      patientName: z.string(),
      lastVisit: z.string(),
    },
  },
})

const systemTexts: string[] = []

const briefing = clinic.agent({
  name: 'briefing',
  model: openai('gpt-5.6-luna'),
  context: [
    clinic.context.system(
      (c) => `Brief the clinician on ${c.state.patientName}, last seen ${c.state.lastVisit}.`,
    ),
    clinic.context.history(),
    clinic.context((c) => {
      for (const e of c.events) {
        if (e.type === 'system') systemTexts.push(e.text)
      }
      return c
    }),
  ],
})

// `runTest` declares its runnable with the erased state schema, so a
// schema-typed agent needs a widening cast to reach it. The run itself is unchanged.
const briefed = await runTest(
  briefing as unknown as Agent,
  [user('Summarise the last visit.'), model('Ada was seen in March for a repeat prescription.')],
  { initialState: { session: { patientName: 'Ada Lovelace', lastVisit: '2026-03-02' } } },
)

const typedView = { systemTexts, status: briefed.status }

typedView

The state was seeded on the session, and the system message was written at render time from the values that were true then. Change the state mid-run and the next turn's system message changes with it — the prompt is a projection of state, the same way the message list is a projection of the ledger.

Reference

The whole vocabulary

Everything app.context offers. Each returns a renderer; put them in the agent's context array in the order you want them applied.

Where this goes next: the ledger these renders read from is the subject of Sessions and state, the outputSchema a typed prompt can quote comes from Structured output, and the scripted model driving every cell on this page is Testing agents without a model.

Step 1

A schema, and its scopes

State is declared on the app, as Zod types grouped by scope. The scopes are session (this conversation), the shared scopes user, patient, practice, org and team (each keyed by an id the session carries, so several sessions can address the same one), and temp (one invocation, never recorded). Declare only the scopes you use.

The schema is a compile-time contract and a defaults table. It types every read and write below, and its .default(…) values are filled in when state is seeded through it — which step 3 does.

Step 2

Writing state from a tool

A tool's ctx.state is the session scope at the top level, with the shared scopes and temp hanging off it: ctx.state.stage, ctx.state.user.displayName, ctx.state.temp.scratch. There are two spellings: assign a key, or hand ctx.state.update(changes) a batch of them. Both follow the same rule — every key that changes appends its own state_change event, a deep-equal value records nothing, and undefined deletes the key.

import { adk } from '@animahealth/adk'
import { MockAdapter } from '@animahealth/adk/testing'
import { z } from 'zod'

const schema = {
  session: {
    stage: z.enum(['intake', 'collecting', 'triaged']).default('intake'),
    concerns: z.array(z.string()).default([]),
  },
  user: {
    displayName: z.string().default('friend'),
  },
}

// The model on this page is a scripted stand-in, so every cell runs with no key. Step 3 writes
// the script; everything else is the shipped runtime.
const scriptedModel = new MockAdapter()

const app = adk({ name: 'triage', schema, adapters: { openai: scriptedModel } })

const noteConcern = app.tool({
  name: 'note_concern',
  description: 'Record one concern the patient reports.',
  schema: z.object({ concern: z.string() }),
  execute: (ctx) => {
    ctx.state.concerns = [...ctx.state.concerns, ctx.args.concern]
    ctx.state.stage = 'collecting'
    return { concerns: ctx.state.concerns }
  },
})

const triage = app.agent({
  name: 'triage',
  model: { provider: 'openai', name: 'gpt-5.6-luna' },
  context: [app.context.system('Log every concern with note_concern.'), app.context.history()],
  tools: [noteConcern],
})

const built = { scopes: Object.keys(app.schema), agent: triage.name, tool: noteConcern.name }

built

temp is scratch space held in memory for the invocation, and reading or writing it outside an invocation throws.

Step 3

Run it, then read state

setResponses hands the scripted model this run's two turns: one that calls the tool, one that answers. Everything else is the ordinary run path — the tool really executes, and no key or network is involved. input.initialState seeds the session before the first turn, scope by scope, and the app's schema fills the rest in from .default(…) — which is why stage starts at 'intake' and concerns at [] without either being named.

scriptedModel.setResponses([
  { toolCalls: [{ name: 'note_concern', args: { concern: 'sore throat' } }] },
  { text: 'Noted a sore throat. Anything else?' },
])

const run = await app.run(triage, {
  input: {
    message: 'I have a sore throat.',
    initialState: { session: {}, user: { displayName: 'Ada' } },
  },
})

const afterRun = { stage: run.state.stage, concerns: run.state.concerns }

afterRun

The run is over; the session is not. run.session is the same session object the tool wrote to, and its state is recomputed from the events on every read. Nothing was saved to a state table — replay is the storage.

Step 4

The audit trail

Every write left a state_change event carrying its scope, its source, and a changes list of { key, oldValue, newValue }. That is the audit: any value in the state can be traced to the event that set it, what it replaced, and which invocation was running.

run.session.events.flatMap((event) =>
  event.type === 'state_change'
    ? [{ scope: event.scope, source: event.source, changes: event.changes }]
    : [],
)

Three sources tell you who moved the value. direct is a write from outside an invocation — the seeding above. mutation is a write from inside one — the tool. observation is not a write at all: it records the value an invocation read from a shared scope, whose storage is bound to the session from outside and can move between reads. Without that binding — as on this page — the seeded user value sits in the ledger, but a tool reading ctx.state.user.displayName finds nothing.

Step 5

Snapshots and time travel

Because state is derived, it can be derived at any point in the past. session.stateAt(index) replays the events up to that index and returns a snapshot: sessionState, scopedStates for the shared scopes, plus the status, currentAgentName, yieldedTools and invocationTree as they stood then. session.eventIndexOf(eventId) maps an event id to its index; session.forkAt(index) returns a new session carrying the events up to that point, so an alternate history can be run without disturbing this one.

const timeline = run.session.events.flatMap((event, index) =>
  event.type === 'state_change'
    ? [{ index, stage: run.session.stateAt(index).sessionState.stage }]
    : [],
)

const forked = run.session.forkAt(run.session.events.findIndex((e) => e.type === 'tool_call'))

const timeTravel = {
  timeline,
  fork: { events: forked.events.length, state: { ...forked.state }, id: forked.id },
}

timeTravel

The fork holds the state as it was when the model asked for the tool, before the tool ran, and it has its own session id. Same mechanism as the audit trail, read forwards instead of backwards. Where those events outlive the process is a separate choice — adk({ store }), covered in Where a sleeping agent lives.

The seam

The ledger is not the context

The ledger is the durable record; what the model sees is re-rendered from it before every model call by the agent's context renderers, so no state_change reaches the prompt unless a renderer puts it there. Which events become messages, and how state is injected into them, belongs to What the model actually sees.

The axis

Two moments at which one agent can hand work to another

Five primitives gave you the vocabulary: agent, step, sequence, parallel, loop. Those are the first moment — you write the graph, and the runner walks it. The second moment is inside a running step or tool, where the code that decides already knows what the data looks like. Both write to the same session, and one field separates them: a container's child carries a parentInvocationId and nothing else, while a handed-off child also carries a handoffOrigin naming the verb.

The three verbs live on the context object, so they are available in any step and in any tool's execute — StepContext and ToolContext both extend OrchestrationContext. Every cell below but the last scripts the model with the test kit and needs no key. The last one asks a real model, so paste a key if you want it; it stays in this browser.

Step 1

Composition is data, and the result is a projection

Containers nest without ceremony: a parallel is a legal child of a sequence, and a step between them sees everything both wrote. Nothing is passed along a wire. Below, two agents run concurrently, a step counts what they said, and a third agent writes the summary.

import { adk, isAnnotationEvent, isAssistantEvent, isModelEndEvent } from '@animahealth/adk'
import { mockAgent, runTest, user, model } from '@animahealth/adk/testing'

const app = adk()

const scan = mockAgent('scan')
const risk = mockAgent('risk')
const writeUp = mockAgent('write_up')

// A parallel nested inside a sequence, with your own code in between.
const checks = app.parallel({ name: 'checks', runnables: [scan, risk] })

const tally = app.step({
  name: 'tally',
  execute: (ctx) => {
    const replies = ctx.session.events.filter(isAssistantEvent).length
    ctx.note(`${replies} replies before the write-up`, { kind: 'mark' })
    ctx.output({ repliesSoFar: replies })
  },
})

const review = app.sequence({ name: 'review', runnables: [checks, tally, writeUp] })

const reviewRun = await runTest(review, [
  user('Review this pull request.'),
  model('No secrets in the diff.'),
  model('Two risky migrations.'),
  model('Ship it once the migrations are split.'),
])

const composition = {
  status: reviewRun.status,
  modelCalls: reviewRun.events.filter(isModelEndEvent).length,
  outputText: reviewRun.result.output.text,
  outputValue: reviewRun.result.output.value,
  outputItems: reviewRun.result.output.items.length,
  notes: reviewRun.events.filter(isAnnotationEvent).map((e) => e.message),
}

composition

Three agents, three scripted replies, three model calls — the step costs none. Read the output fields carefully, because this is where composition surprises people. A container does not return its last child's return value. output.text is the last assistant event in the session and output.items is every assistant event in it, both computed from the ledger when the run finishes.

The stopping rule follows the same logic. A sequence abandons the rest of its children when a child comes back error, aborted, max_steps, or yielded_tool; anything else and the next child runs. A step that calls ctx.skip() therefore skips itself, not the sequence. A loop applies the same four-way test to each iteration, and re-evaluates its while predicate before every one.

examples/staticFlow.ts is this composition at full size: parallel research, a planning sequence, a revision loop that stops on the editor's score, then a yield for sign-off.

Step 2

run, spawn, dispatch: the same handoff, three waits

The three verbs differ only in how the caller waits. ctx.run awaits a SubRunResult. ctx.spawn starts the agent and hands you a SpawnHandle you can wait() on later or abort(). ctx.dispatch starts it and returns only its name and invocation id — there is no result to collect. All three take the agent plus a message, or { input, timeout } when you want more: input.state seeds the child's temp state, and timeout is honoured by run and by a handle's wait() — dispatch, having nothing to wait on, ignores it. All three run on the session you are already in.

import { isInvocationStartEvent } from '@animahealth/adk'

const grader = mockAgent('grader')
const summariser = mockAgent('summariser')
const auditor = mockAgent('auditor')

const triage = app.step({
  name: 'triage',
  execute: async (ctx) => {
    const graded = await ctx.run(grader, 'Grade this ticket.') // wait here
    const pending = ctx.spawn(summariser, 'Summarise the thread.') // wait later
    const sent = ctx.dispatch(auditor, 'Write the audit line.') // never wait
    const summary = await pending.wait()
    ctx.output({
      ranInline: graded.output.text,
      spawned: `${pending.agentName} · ${summary.status}`,
      dispatched: sent.agentName,
    })
  },
})

const triageRun = await runTest(triage, [
  user('Ticket 41 came in.'),
  model('P2'),
  model('The customer cannot log in.'),
  model('audit ok'),
])

const handoffs = {
  value: triageRun.result.output.value,
  origins: triageRun.events
    .filter(isInvocationStartEvent)
    .map((e) => `${e.agentName} ← ${e.handoffOrigin?.type ?? 'root'}`),
}

handoffs

Four invocations, and each one says how it was reached. That stamp is the reason the flat ledger stays readable: handoffOrigin carries the type and the parent's invocation id, so a reviewer can rebuild the call tree from rows alone. A step run at the top has no origin.

Nothing awaited the auditor, and it is in the ledger anyway — because fire-and-forget describes the caller, not the run. A spawned or dispatched agent is registered as a producer on the run's event channel, and the run's promise resolves only when every producer has finished. The parent's own invocation closes first, while the run stays open until the work finishes. To outlive the run, you need a store and a second call, not a background task.

ctx.run rejects an agent that yields. A delegate stopping to ask a human has nowhere to put the question, so it throws and points you at yielding tools in the parent agent instead.

Step 3

Transfer: the agent that replaces the one that called it

The fourth handoff has no verb. Return a runnable from a tool's execute, or from a step's, and the runtime treats it as a transfer: the current agent's invocation ends and the target's begins in its place. There is no nesting and no return trip. This is how a front desk hands a caller to a specialist.

import { openai } from '@animahealth/adk/openai'
import { z } from 'zod'

const billing = mockAgent('billing')

const handOver = app.tool({
  name: 'hand_over',
  description: 'Give the conversation to the billing specialist',
  schema: z.object({ reason: z.string() }),
  // Returning a runnable is the transfer. Nothing else about the tool changes.
  execute: () => billing,
})

const frontDesk = app.agent({
  name: 'front_desk',
  model: openai('gpt-5.6-luna'),
  context: [app.context.system('Hand billing questions over.'), app.context.history()],
  tools: [handOver],
})

const handedOver = await runTest(frontDesk, [
  user('My invoice is wrong.'),
  model({ toolCalls: [{ name: 'hand_over', args: { reason: 'invoice dispute' } }] }),
  model('I can see it — the VAT line is duplicated.'),
])

const transferred = {
  status: handedOver.status,
  finalText: handedOver.result.output.text,
  origins: handedOver.events
    .filter(isInvocationStartEvent)
    .map((e) => `${e.agentName} ← ${e.handoffOrigin?.type ?? 'root'}`),
  ledger: handedOver.events.map((e) => e.type),
}

transferred

Read the ledger tail: front_desk reaches invocation_end before billing opens its invocation_start. That is the difference from ctx.run, which nests the callee inside the caller. The run status is completed, not something transfer-specific — the caller is gone, so the target's outcome is the run's outcome. Temp state follows the transfer; the rest of the session was never separate.

A transfer that happens inside a ctx.run is resolved before that promise settles, so the calling step sees the final agent's result and never has to chase a chain. One restriction: an afterTool hook cannot transfer, because the tool result has already been written — see guardrails for where each hook can and cannot intervene.

The cells above call the verbs from your own code, which is where a deterministic handoff belongs. For all four wired instead as tools a model picks between, read examples/dynamicFlow.ts.

Step 4

Two wrappers you would otherwise write twice

gated(runnable, check) puts a step in front of a runnable. The check receives a StepContext; return nothing and the runnable runs, call ctx.skip() and it does not. cached(runnable, { key, scope, ttlMs }) is that same gate with the check written for you: if the state key already holds a value, skip. Both return a Sequence carrying the wrapped runnable's own name, so wrapping does not rename anything in the ledger.

Both read state, and state lives in scopes on the session — session is the one every runnable in the run shares, which is why the runs below seed it through initialState. Sessions and state is the chapter.

import { cached, gated } from '@animahealth/adk'

const enrich = mockAgent('enrich')
const translate = mockAgent('translate')

// Run the translator unless the ticket is already in English.
const guarded = gated(translate, (ctx) => {
  if (ctx.state.locale === 'en') ctx.skip()
})

// Run the enricher only when session state has no profile yet.
const memoised = cached(enrich, { key: 'profile', scope: 'session' })

const pipeline = app.sequence({ name: 'pipeline', runnables: [memoised, guarded] })

const cold = await runTest(pipeline, [user('Hallo'), model('profile built'), model('Hello')])

const warm = await runTest(pipeline, [user('Hallo'), model('Hello')], {
  initialState: { session: { profile: { name: 'Ada' }, locale: 'de' } },
})

const english = await runTest(pipeline, [user('Hello'), model('profile built')], {
  initialState: { session: { locale: 'en' } },
})

const patterns = {
  cold: cold.events.filter(isAssistantEvent).map((e) => e.agentName),
  warmCacheHit: warm.events.filter(isAssistantEvent).map((e) => e.agentName),
  alreadyEnglish: english.events.filter(isAssistantEvent).map((e) => e.agentName),
  whatCachedBuilt: `${memoised.kind} '${memoised.name}' wrapping ${memoised.runnables.map((r) => r.name).join(', ')}`,
}

patterns

Cold, both run. Warm, the cached agent is skipped and only the translator speaks. Already in English, the gate skips the translator instead. The last field shows what cached built: a sequence named enrich whose single child is a step named enrich_gate, which returns the wrapped agent when the check passes. Nothing is hidden — it is the routing step from Five primitives, written once.

scope picks which state scope the key is read from and defaults to session; ttlMs adds an age test, measured from the state_change event that last wrote the key. An expired or absent key runs the runnable again. Neither wrapper ever writes the key; the wrapped runnable does, through its output config or a step of its own.

Step 5

A runnable that has not chosen an app yet

app.agent and friends bake in one app: its schema, its hooks, its error handlers. That is what you want inside a program and wrong for a library. spec defers the binding. spec.sequence()(fn) returns a function of an app, and app.use(thatSpec) calls it — so the same definition yields a different runnable per app, with each app's own configuration already applied.

import { spec } from '@animahealth/adk'

const other = adk({ name: 'other-app' })

// No app in sight — `boundApp` arrives when someone uses it.
const triageSpec = spec.sequence()((boundApp) => ({
  name: 'triage_flow',
  runnables: [
    boundApp.step({
      name: 'stamp',
      execute: (ctx) => {
        ctx.state.stamped = true
      },
    }),
    boundApp.agent({
      name: 'classifier',
      model: openai('gpt-5.6-luna'),
      context: [boundApp.context.system('Answer in one word.'), boundApp.context.history()],
    }),
  ],
}))

const here = app.use(triageSpec)
const there = other.use(triageSpec)

const specRun = await runTest(here, [user('My card was declined.'), model('billing')])

const reuse = {
  distinctRunnables: here !== there,
  built: `${here.kind} '${here.name}': ${here.runnables.map((r) => `${r.kind}:${r.name}`).join(' → ')}`,
  said: specRun.events.filter(isAssistantEvent).map((e) => e.text),
}

reuse

One definition, two runnables, and the cell ran the one bound to app. There is a spec factory per kind — tool, step, context, agent, sequence, parallel, loop — each taking an optional schema so the callback's ctx is typed before any app exists. This is how a package ships an agent that a consuming app finishes configuring, and it is the only reason to reach past app.*.

Step 6

Below the graph: one-shot calls and bounded concurrency

Some work is not an agent. Judging an answer, extracting a field, scoring a candidate — no tools, no memory of the conversation, no reason to appear in the ledger. app.ask(prompt, opts) is that call: a no-tools agent on a fresh session, so nothing it does touches yours. Pass a Zod schema and the return type is the parsed value rather than text; pass system, signal, or retries to shape the attempt. The model comes from opts.model or the app's defaultModel, and if neither is set the call throws rather than guessing.

fanout(thunks, { limit }) is the other half: run zero-argument async functions with at most limit in flight. It returns results in input order, turns a rejected thunk into null instead of failing the batch, and never rejects. It knows nothing about agents — it is the concurrency primitive the workflow runtime uses, exported because fanning out judgements is the common case.

This cell calls OpenAI with the key from the box above. Three tickets, two at a time, each answered as a typed object.

import { fanout } from '@animahealth/adk'

const live = adk({ defaultModel: openai('gpt-5.6-luna') })

const Verdict = z.object({
  severity: z.enum(['low', 'medium', 'high']),
  team: z.string(),
})

const tickets = [
  'The invoice VAT line is duplicated.',
  'The app crashes on every login attempt.',
  'Please send a copy of last month’s receipt.',
]

// fanout takes zero-argument thunks, so each ask is wrapped rather than started.
const askVerdict = (ticket: string) => () =>
  live.ask(`Route this support ticket. Ticket: ${ticket}`, { schema: Verdict })

const verdicts = await fanout(tickets.map(askVerdict), { limit: 2 })

verdicts

Three verdicts, in the order the tickets were written, whatever order they finished in. Only OutputParseError is retried — see Structured output — so a provider error surfaces immediately instead of being spent on re-asks. If you need tools, state, or a resumable pause, you have outgrown ask: build an agent and put it in the graph.

That is the whole handoff surface. Sessions and state covers the state these agents share, what the model actually sees covers what each one is shown, and dynamic workflows covers the experimental loader that builds a graph like this one from a file.

Step 1

A tool that yields

A tool yields by declaring a yieldSchema: the shape of the answer it needs from outside. That is the only new field. app.tool requires an execute or a yieldSchema, so a yielding tool may have no execute — then the supplied input becomes the tool result.

Three optional hooks bracket the pause. prepare runs before it and can rewrite the arguments or record state. execute and finalize run after it, with ctx.input typed by the yieldSchema; otherwise they behave as Tools describes.

import { adk } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'
import { z } from 'zod'

const app = adk()

const requestApproval = app.tool({
  name: 'request_approval',
  description: 'Ask a human to approve an action before performing it',
  schema: z.object({ action: z.string() }),
  // The answer this tool waits for. Its presence is what makes the tool yield.
  yieldSchema: z.object({ approved: z.boolean(), note: z.string().optional() }),
  prepare: (ctx) => {
    // Runs before the pause: park what a human (or another service) needs to see.
    ctx.state.pendingAction = ctx.args.action
    return ctx.args
  },
  execute: (ctx) => {
    // Runs after the pause, with the supplied answer already validated.
    const decision = ctx.input
    if (!decision?.approved) return { action: ctx.args.action, status: 'declined' }
    return { action: ctx.args.action, status: 'performed', note: decision.note }
  },
  finalize: (ctx) => {
    ctx.state.pendingAction = undefined
  },
})

const operator = app.agent({
  name: 'operator',
  model: openai('gpt-5.6-luna'),
  context: [
    app.context.system('Ask for approval before any destructive action.'),
    app.context.history(),
  ],
  tools: [requestApproval],
})

operator.name

Step 2

The run that stops

Script the model, supply no answer, and the run does not complete: it comes back yielded_tool, carrying the calls it is waiting on. Each is a tool_yield event with a callId — the handle you answer it by — plus the tool's name and the arguments prepare returned. The session says awaiting_input, and session.yieldedTools is the still-unanswered subset. State written in prepare is already durable.

import { runTest, user, model } from '@animahealth/adk/testing'

const paused = await runTest(operator, [
  user('Delete the 2019 archive'),
  model({
    toolCalls: [{ name: 'request_approval', args: { action: 'delete the 2019 archive' } }],
  }),
])

const pausedRun = paused.result

const waiting = {
  runStatus: pausedRun.status,
  sessionStatus: paused.session.status,
  askedFor:
    pausedRun.status === 'yielded_tool'
      ? pausedRun.yieldedTools.map((y) => ({ name: y.name, callId: y.callId, args: y.args }))
      : [],
  stateWhileAsleep: paused.session.state.pendingAction,
}

waiting

Before resuming anything, you can ask the ledger whether it is answerable. validateResumeState reads the events and returns one entry per yield that has no input yet; assertReadyToResume is the same check that throws. Both take events, not a live object, so a resume can be vetted anywhere the rows can be read.

import { validateResumeState, assertReadyToResume } from '@animahealth/adk'

let guard
try {
  assertReadyToResume(paused.events)
  guard = 'ready to resume'
} catch (error) {
  guard = error instanceof Error ? error.message : String(error)
}

const readiness = { unresolved: validateResumeState(paused.events), guard }

readiness

Step 3

What a sleeping agent is

This is the whole of the paused agent. No process, no timer, no held connection — an append-only list of events that stops at invocation_yield. The absent event is the point: there is no invocation_end. An unterminated invocation whose last event is a yield is the definition of a sleeping agent, and it costs exactly what those rows cost to store.

paused.events.map((event) => event.type)

Those rows outlive the process only if the app has a store, which is Stores, and what else the session around them carries is Sessions and state.

Step 4

Supplying the input

Answering is one call: session.input.tool({ callId, input }). It appends a tool_input event, which makes the yield resolved; the next run picks it up. The test kit has a step for it — input(...), keyed by tool name, placed after the model turn that yielded. So the whole pause-and-resume fits in one script.

import { input, getToolResults } from '@animahealth/adk/testing'

const resumed = await runTest(operator, [
  user('Delete the 2019 archive'),
  model({
    toolCalls: [{ name: 'request_approval', args: { action: 'delete the 2019 archive' } }],
  }),
  // The answer a human would give — supplied here as session.input.tool would supply it.
  input({ request_approval: { approved: true, note: 'Owner signed off' } }),
  model('Archive deleted.'),
])

const settled = {
  status: resumed.status,
  unresolved: validateResumeState(resumed.events).length,
  toolResults: getToolResults(resumed.events),
  pendingStateClearedByFinalize: resumed.session.state.pendingAction === undefined,
  ledger: resumed.events.map((event) => event.type),
}

settled

The input is parsed against the yieldSchema before execute sees it. A mismatched answer does not throw and does not hang: it becomes a tool_result carrying an Invalid input error, which the model reads on the next turn like any other tool failure.

Read the tail of that ledger: tool_yield and invocation_yield close the first run, tool_input is the answer arriving, invocation_resume reopens the same invocation, and only then does tool_result appear. The agent was never running in between.

Step 5

Yielding for a message, not a tool

The other stop is conversational. An agent configured yields: true parks after each terminal reply instead of completing, waiting for the next user message — the status is yielded_message and the result carries a yieldedInvocationId rather than tool calls. Realtime models default to this. Answering is session.input.message(...); in the test kit it is another user(...) step.

const intake = app.agent({
  name: 'intake',
  model: openai('gpt-5.6-luna'),
  context: [app.context.system('Ask one question at a time.'), app.context.history()],
  tools: [],
  yields: true,
})

const asked = await runTest(intake, [user('I want to book a room'), model('Which date?')])

const answered = await runTest(intake, [
  user('I want to book a room'),
  model('Which date?'),
  user('Next Tuesday'),
  model('Booked for next Tuesday.'),
])

const conversation = {
  afterOneTurn: asked.status,
  afterTwoTurns: answered.status,
  said: answered.events.flatMap((event) => (event.type === 'assistant' ? [event.text] : [])),
  ledger: answered.events.map((event) => event.type),
}

conversation

Both runs end yielded_message: an agent that yields never completes on its own, it parks. The second ledger shows the shape of a conversation under this rule — invocation_yield, then user, then invocation_resume into the same invocation. A chat that has been idle for a month and one that replied a second ago are the same rows.

Step 6

The same protocol in a server

Nothing above changes when the pause spans a real request boundary: because the wait is stored rather than held, the process that asks the question and the process that receives the answer need not be the same one, or alive at the same time. The Bookings sample puts that loop behind a running app, and the request that resumes a row — the input.tools you post — belongs to Serving.

Step 1

The demo, end to end

Four commands — ask, pending, approve, deny. The first one starts a run and does not finish it.

Start it:

$ npx tsx src/cli.ts ask "I need physio on Tuesday afternoon, for Alex Doe"
session session_8c1f…

agent  Tuesday 14:30 with R. Ellis is open — shall I book it?

paused book_slot {"slotId":"slot-02","bookedFor":"Alex Doe"}
       npx tsx src/cli.ts approve session_8c1f…
       npx tsx src/cli.ts deny session_8c1f… "why not"

The paused line is the yield. The model asked for book_slot; the runtime recorded the request and stopped the run rather than executing it. Then the process exited. No held connection — the session is rows on disk, and the pause is one of them.

Come back tomorrow, from another terminal. pending asks the store what is still unanswered; approve answers it.

$ npx tsx src/cli.ts pending
session_8c1f…  book_slot  {"slotId":"slot-02","bookedFor":"Alex Doe"}

$ npx tsx src/cli.ts approve session_8c1f…

agent  Booked — Tuesday 14:30 with R. Ellis.
booked CLINIC-001 — physiotherapy with R. Ellis, Tuesday 14:30, for Alex Doe

approve read the session out of SQLite, handed { approved: true } to the suspended call, and the tool's execute ran for the first time — in a process that did not exist when the model decided to call it. The booked line is typed state: session.state.confirmation, declared in the app's schema and read back intact after a round trip through the file.

Declining takes the same path, and the reason reaches the model:

$ npx tsx src/cli.ts deny session_8c1f… "Alex cannot do afternoons"

agent  Understood — 09:15 on Monday is the other physio slot. Shall I take it?

Step 2

The world it books against — src/clinic.ts

The clinic is a constant and a Map, so the sample needs no database, no container and no network, and swapping these functions for real queries changes nothing above them. The agent only ever sees tools.

/** The week, as `[id, service, clinician, day, time]`. Weekday names never go stale. */
const TIMETABLE = [
  ['slot-01', 'physiotherapy', 'R. Ellis', 'Monday', '09:15'],
  ['slot-02', 'physiotherapy', 'R. Ellis', 'Tuesday', '14:30'],
  ['slot-03', 'physiotherapy', 'J. Okafor', 'Tuesday', '16:00'],
  ['slot-04', 'dental-hygiene', 'M. Haas', 'Tuesday', '11:00'],
  ['slot-05', 'dental-hygiene', 'M. Haas', 'Thursday', '15:45'],
  ['slot-06', 'eye-test', 'S. Vance', 'Wednesday', '10:30'],
  ['slot-07', 'eye-test', 'S. Vance', 'Friday', '13:00'],
] as const satisfies ReadonlyArray<readonly [string, Service, string, string, string]>

const SLOTS: readonly Slot[] = TIMETABLE.map(([id, service, clinician, day, time]) => ({
  id,
  service,
  clinician,
  day,
  time,
}))

Three readers come off that list. openSlots(filter) returns the unbooked slots matching an optional service and weekday; findSlot and isBooked are the two lookups the booking tool needs. One function writes — bookSlot — and it is the side effect a human approves.

Step 3

The whole program — src/bookings.ts

One app, one state schema, two tools, one agent. Everything the ADK contributes to this sample is in this file. Start here; the rest is scaffolding around it.

import { fileURLToPath } from 'node:url'
import { z } from 'zod'

import { adk } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'
import { sqliteStore } from '@animahealth/adk/stores/sqlite'

import { SERVICES, bookSlot, findSlot, isBooked, openSlots } from './clinic.js'

Three imports off the package: the core, the OpenAI model factory, the SQLite store. Providers and stores are subpath exports and optional peers — importing the core pulls in neither.

/**
 * What a completed booking looks like. Declaring it in the app schema is what makes
 * `session.state.confirmation` typed everywhere downstream, including after it is read back out of
 * SQLite in a different process.
 */
const confirmation = z.object({
  reference: z.string(),
  slotId: z.string(),
  service: z.string(),
  clinician: z.string(),
  day: z.string(),
  time: z.string(),
  bookedFor: z.string(),
})

export type Confirmation = z.infer<typeof confirmation>

export const app = adk({
  name: 'bookings',
  schema: { session: { confirmation: confirmation.optional() } },
  store: sqliteStore(DB_PATH),
})

schema.session is what makes state typed downstream. A session has no confirmation until a booking is approved, so the field is optional. store decides where the session sleeps: one file, created on first use, safe to delete.

The deterministic tool comes first.

/** Deterministic. The model chooses the arguments; this code decides the answer. */
const searchSlots = app.tool({
  name: 'search_slots',
  description: 'List the open appointment slots at the clinic, optionally filtered.',
  schema: z.object({
    service: z.enum(SERVICES).optional().describe('Only slots for this service'),
    day: z.string().optional().describe('Only slots on this weekday, e.g. "Tuesday"'),
  }),
  execute: (ctx) => ({ slots: openSlots(ctx.args) }),
})

And the yielding one — the only structural difference is yieldSchema.

/**
 * The yielding tool. `yieldSchema` is the contract for the human's answer; because it is present,
 * ADK suspends the run at the call instead of running `execute`. `execute` runs later, once, with
 * that answer in `ctx.input`.
 */
const bookSlotTool = app.tool({
  name: 'book_slot',
  description:
    'Book one open slot. A human reviews every call to this tool before it takes effect, so propose a single slot and call it once.',
  schema: z.object({
    slotId: z.string().describe('The id of an open slot, from search_slots'),
    bookedFor: z.string().describe('The name the appointment is under'),
  }),
  yieldSchema: z.object({
    approved: z.boolean().describe('true to book the slot, false to decline it'),
    note: z.string().optional().describe('Why it was declined — the agent reads this'),
  }),
  execute: (ctx) => {
    const slot = findSlot(ctx.args.slotId)
    if (!slot) {
      return { booked: false as const, reason: `There is no slot called ${ctx.args.slotId}.` }
    }
    if (isBooked(slot.id)) {
      return { booked: false as const, reason: `${slot.id} has already been booked.` }
    }
    if (!ctx.input?.approved) {
      return {
        booked: false as const,
        reason: ctx.input?.note ?? 'A human declined this booking. Offer a different slot.',
      }
    }

    const booking = bookSlot(slot, ctx.args.bookedFor)
    // Typed, and durable: this write becomes a state_change event, committed to SQLite with the
    // rest of the session, and readable as `session.state.confirmation` forever after.
    ctx.state.confirmation = booking
    return { booked: true as const, ...booking }
  },
})

ctx.args is what the model asked for; ctx.input is what the human answered, already validated against yieldSchema.

The agent is the rest of the file.

export const bookingAgent = app.agent({
  name: 'bookings',
  model: openai('gpt-5.6-luna'),
  context: [
    app.context.system(
      [
        'You book appointments for a small clinic.',
        'Call search_slots before you offer anything. Never invent a slot or a time.',
        'Offer one slot at a time, then call book_slot for it. That call pauses for a human.',
        'If a booking is declined, read the note and offer the next best open slot.',
        'Answer in one or two sentences.',
      ].join('\n'),
    ),
    app.context.history(),
  ],
  tools: [searchSlots, bookSlotTool],
})

The system prompt does the work a schema cannot: it tells the model to search before it offers, and to propose one slot at a time — because every book_slot call spends a human's attention. The mechanism itself, in isolation, is Stopping to ask: prepare, finalize, the resume guard, and yielding for a message rather than a tool.

Step 4

Four commands, two processes — src/cli.ts

Nothing here is special machinery. ask is the whole lifecycle: create a session, put a message in, run, commit, print.

async function ask(text: string): Promise<void> {
  requireKey()
  const session = await app.sessions.create()
  session.input.message(text)
  const result = await app.run(bookingAgent, { session })
  await app.sessions.commit(session)

  console.log(`session ${session.id}`)
  report(session, result.output.text)
}

app.run returns when the run stops — completed or yielded, it is the same call either way, and the status says which. The commit is what makes a pause durable: events buffer in memory until it is called.

Printing is where the pause becomes visible.

/** Print what the agent said, and what it is now waiting for. */
function report(session: Session<typeof app.schema>, text: string | undefined): void {
  if (text) console.log(`\nagent  ${text}`)

  const confirmation = session.state.confirmation
  if (confirmation) {
    console.log(
      `booked ${confirmation.reference} — ${confirmation.service} with ${confirmation.clinician}, ` +
        `${confirmation.day} ${confirmation.time}, for ${confirmation.bookedFor}`,
    )
  }

  const [waiting] = session.yieldedTools
  if (waiting) {
    console.log(`\npaused ${waiting.name} ${JSON.stringify(waiting.args)}`)
    console.log(`       npx tsx src/cli.ts approve ${session.id}`)
    console.log(`       npx tsx src/cli.ts deny ${session.id} "why not"`)
  }
}

session.yieldedTools is the unanswered set — empty after a completed run, one entry after this one. session.state.confirmation is typed by the app schema, so the fields interpolated into the booked line are checked at compile time, not hoped for at runtime.

The queue of things waiting for a human is therefore a query, not a broker:

async function pending(): Promise<void> {
  const sessions = await app.sessions.list()
  let found = 0

  for (const { id } of sessions) {
    const session = await app.sessions.get(id)
    const [waiting] = session?.yieldedTools ?? []
    if (!session || !waiting) continue
    found++
    console.log(`${session.id}  ${waiting.name}  ${JSON.stringify(waiting.args)}`)
  }

  if (found === 0) console.log(`nothing is waiting for a human (${DB_PATH})`)
}

And the resume is one line of protocol wrapped in the same run-and-commit:

async function decide(sessionId: string, approved: boolean, note?: string): Promise<void> {
  requireKey()
  const session = await app.sessions.get(sessionId)
  if (!session) {
    throw new Error(`No session ${sessionId}. Try: npx tsx src/cli.ts pending`)
  }

  const [waiting] = session.yieldedTools
  if (!waiting) {
    throw new Error(`Session ${sessionId} is not waiting on anything.`)
  }

  // The resume. `callId` ties the answer to the exact suspended call; `input` is validated
  // against the tool's yieldSchema before execute() ever sees it.
  session.input.tool({ callId: waiting.callId, input: { approved, note } })
  const result = await app.run(bookingAgent, { session })
  await app.sessions.commit(session)

  report(session, result.output.text)
}

After that it is ask again — run, commit, print — except this run starts inside a tool call that a previous process left open, and it is approve that pays for the booking's side effect.

Step 5

The same arc, with no key — test/bookings.test.ts

runTest replaces exactly one thing: the model. Everything else still runs — the tools, the ledger, the yield. So the assertion worth making is available on any fork, with no credentials.

import { beforeEach, describe, expect, test } from 'vitest'

import type { Runnable } from '@animahealth/adk'
import { getToolCalls, getToolResults, input, model, runTest, user } from '@animahealth/adk/testing'

import { bookingAgent } from '../src/bookings.js'
import { isBooked, openSlots, resetClinic } from '../src/clinic.js'

/**
 * `runTest` is typed against the schema-erased `Runnable`, so an agent built on an app that
 * declares a state schema needs this cast. Types only — at runtime it is the same object
 * `app.run()` takes.
 */
const agent = bookingAgent as unknown as Runnable

beforeEach(resetClinic)

First the pause. Script the model into calling book_slot, then stop.

describe('book_slot yields', () => {
  test('the run stops at the call and nothing is booked', async () => {
    const run = await runTest(agent, [
      user('Book slot-02 for Alex Doe.'),
      model({
        toolCalls: [{ name: 'book_slot', args: { slotId: 'slot-02', bookedFor: 'Alex Doe' } }],
      }),
    ])

    expect(run.status).toBe('yielded_tool')
    expect(run.session.yieldedTools).toHaveLength(1)
    expect(run.session.yieldedTools[0]?.name).toBe('book_slot')

    // The pause is real: execute() has not run, so the world is untouched.
    expect(isBooked('slot-02')).toBe(false)
    expect(run.session.state.confirmation).toBeUndefined()
  })
})

Status yielded_tool, one entry waiting, the slot still open and no confirmation in state.

Then the two resume cases. input(...) stands in for what a human sends hours later from another process — in a script it is one line in the right place.

  test('approval executes the booking and returns a typed confirmation', async () => {
    const run = await runTest(agent, [
      user('Book slot-02 for Alex Doe.'),
      model({
        toolCalls: [{ name: 'book_slot', args: { slotId: 'slot-02', bookedFor: 'Alex Doe' } }],
      }),
      // The human's answer, shaped by the tool's yieldSchema. In the CLI this arrives from a
      // separate process, minutes or days later.
      input({ book_slot: { approved: true } }),
      model('Booked — Tuesday 14:30 with R. Ellis.'),
    ])

    expect(run.status).toBe('completed')
    expect(isBooked('slot-02')).toBe(true)
    expect(run.session.state.confirmation).toEqual({
      reference: 'CLINIC-001',
      slotId: 'slot-02',
      service: 'physiotherapy',
      clinician: 'R. Ellis',
      day: 'Tuesday',
      time: '14:30',
      bookedFor: 'Alex Doe',
    })
  })

And the demo's other branch, where the reason travels back to the model:

  test('a refusal leaves the slot open and hands the reason back to the agent', async () => {
    const run = await runTest(agent, [
      user('Book slot-02 for Alex Doe.'),
      model({
        toolCalls: [{ name: 'book_slot', args: { slotId: 'slot-02', bookedFor: 'Alex Doe' } }],
      }),
      input({ book_slot: { approved: false, note: 'Alex cannot do afternoons.' } }),
      model('Understood — 09:15 on Monday is the other physio slot. Shall I take it?'),
    ])

    expect(run.status).toBe('completed')
    expect(isBooked('slot-02')).toBe(false)
    expect(run.session.state.confirmation).toBeUndefined()
    expect(getToolResults(run.events)[0]?.result).toEqual({
      booked: false,
      reason: 'Alex cannot do afternoons.',
    })
  })

The cells below exercise the pause and resume behavior directly in this page.

The same script, running here

The cells below are that test, adapted only as far as this page requires: the substrate serves the ADK, its test kit and zod, so the clinic module is inlined and the SQLite store is dropped. The schema, both tools, the prompt and the agent are the sample's own. Persistence is what a cell cannot demonstrate here, so src/cli.ts above stands as the evidence for it.

import { adk } from '@animahealth/adk'
import type { Runnable } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'
import { z } from 'zod'

// src/clinic.ts and src/bookings.ts, joined and trimmed to what this page can serve: the clinic
// module is inlined, the SQLite store is dropped, two of the seven slots are kept. The schema,
// both tools and the agent are the sample's.
const confirmation = z.object({
  reference: z.string(),
  slotId: z.string(),
  service: z.string(),
  clinician: z.string(),
  day: z.string(),
  time: z.string(),
  bookedFor: z.string(),
})

const SLOTS = [
  { id: 'slot-01', service: 'physiotherapy', clinician: 'R. Ellis', day: 'Monday', time: '09:15' },
  { id: 'slot-02', service: 'physiotherapy', clinician: 'R. Ellis', day: 'Tuesday', time: '14:30' },
]

const ledger = new Map<string, z.infer<typeof confirmation>>()
let nextReference = 1

const openSlots = (filter: { service?: string; day?: string }) =>
  SLOTS.filter(
    (slot) =>
      !ledger.has(slot.id) &&
      (filter.service === undefined || slot.service === filter.service) &&
      (filter.day === undefined || slot.day.toLowerCase() === filter.day.toLowerCase()),
  )

const findSlot = (slotId: string) => SLOTS.find((slot) => slot.id === slotId)
const isBooked = (slotId: string) => ledger.has(slotId)
const resetClinic = () => {
  ledger.clear()
  nextReference = 1
}

const bookings = adk({
  name: 'bookings',
  schema: { session: { confirmation: confirmation.optional() } },
})

const searchSlots = bookings.tool({
  name: 'search_slots',
  description: 'List the open appointment slots at the clinic, optionally filtered.',
  schema: z.object({
    service: z.string().optional().describe('Only slots for this service'),
    day: z.string().optional().describe('Only slots on this weekday, e.g. "Tuesday"'),
  }),
  execute: (ctx) => ({ slots: openSlots(ctx.args) }),
})

const bookSlotTool = bookings.tool({
  name: 'book_slot',
  description:
    'Book one open slot. A human reviews every call to this tool before it takes effect, so propose a single slot and call it once.',
  schema: z.object({
    slotId: z.string().describe('The id of an open slot, from search_slots'),
    bookedFor: z.string().describe('The name the appointment is under'),
  }),
  yieldSchema: z.object({
    approved: z.boolean().describe('true to book the slot, false to decline it'),
    note: z.string().optional().describe('Why it was declined — the agent reads this'),
  }),
  execute: (ctx) => {
    const slot = findSlot(ctx.args.slotId)
    if (!slot) {
      return { booked: false as const, reason: `There is no slot called ${ctx.args.slotId}.` }
    }
    if (isBooked(slot.id)) {
      return { booked: false as const, reason: `${slot.id} has already been booked.` }
    }
    if (!ctx.input?.approved) {
      return {
        booked: false as const,
        reason: ctx.input?.note ?? 'A human declined this booking. Offer a different slot.',
      }
    }

    const booking = {
      reference: `CLINIC-${String(nextReference++).padStart(3, '0')}`,
      slotId: slot.id,
      service: slot.service,
      clinician: slot.clinician,
      day: slot.day,
      time: slot.time,
      bookedFor: ctx.args.bookedFor,
    }
    ledger.set(slot.id, booking)
    ctx.state.confirmation = booking
    return { booked: true as const, ...booking }
  },
})

const bookingAgent = bookings.agent({
  name: 'bookings',
  model: openai('gpt-5.6-luna'),
  context: [
    bookings.context.system(
      [
        'You book appointments for a small clinic.',
        'Call search_slots before you offer anything. Never invent a slot or a time.',
        'Offer one slot at a time, then call book_slot for it. That call pauses for a human.',
        'If a booking is declined, read the note and offer the next best open slot.',
        'Answer in one or two sentences.',
      ].join('\n'),
    ),
    bookings.context.history(),
  ],
  tools: [searchSlots, bookSlotTool],
})

// The sample's test file makes this same cast: runTest takes the schema-erased Runnable.
const agent = bookingAgent as unknown as Runnable

bookingAgent.name

Now the first run, with nothing supplied. It should stop at the call and leave the world untouched.

import { model, runTest, user } from '@animahealth/adk/testing'

resetClinic()

const paused = await runTest(agent, [
  user('Book slot-02 for Alex Doe.'),
  model({ toolCalls: [{ name: 'book_slot', args: { slotId: 'slot-02', bookedFor: 'Alex Doe' } }] }),
])

const stopped = {
  status: paused.status,
  waitingOn: paused.session.yieldedTools.map((y) => ({ name: y.name, args: y.args })),
  slotStillOpen: !isBooked('slot-02'),
  confirmation: paused.session.state.confirmation,
}

stopped

Add the human's answer and the same script completes. The printed ledger carries the whole pause: the yield, the answer arriving, the invocation reopening, and only then the tool result. Between those events, in the sample, is a process boundary.

import { input } from '@animahealth/adk/testing'

resetClinic()

const resumed = await runTest(agent, [
  user('Book slot-02 for Alex Doe.'),
  model({ toolCalls: [{ name: 'book_slot', args: { slotId: 'slot-02', bookedFor: 'Alex Doe' } }] }),
  // What a human sends, hours later, from anywhere. In the sample it arrives from another process.
  input({ book_slot: { approved: true } }),
  model('Booked — Tuesday 14:30 with R. Ellis.'),
])

const settled = {
  status: resumed.status,
  confirmation: resumed.session.state.confirmation,
  ledger: resumed.events.map((event) => event.type),
}

settled

Edit the script and run again — decline it, change the slot id, book a slot that does not exist. The tool's own branches answer, because the tool is real. The kit itself is Testing agents without a model.

Step 6

Run the notebook or build your own application

Press Run all to execute the Bookings flow with a scripted provider. The cells use an in-memory session, so they need no credentials and do not create bookings.db.

For a local application, follow the Node project setup and install the published @animahealth/adk package. The snippets above explain the agent, store, and approval flow; your application supplies its CLI entrypoint and configuration.

Your key

Ten cells run without one

Everything up to the last cell scripts the model with the test kit, so it runs here with no credentials. The final cell asks a real model for a typed object; that one needs a key. It lives in this browser's localStorage and goes only to api.openai.com.

Step 1

A schema on output

An agent's output field accepts a Zod schema — { schema, key?, mode? } — or the name of a key in the app's session schema. Give it a schema and the run hands back the parsed, validated object alongside the text it came from. Build the agent first.

import { adk } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'
import { z } from 'zod'

const app = adk()

const Triage = z.object({
  urgency: z.enum(['routine', 'urgent', 'emergency']),
  symptoms: z.array(z.string()),
  followUpDays: z.number(),
})

const triager = app.agent({
  name: 'triager',
  model: openai('gpt-5.6-luna'),
  context: [app.context.system('Triage the patient message.'), app.context.history()],
  output: { schema: Triage },
})

triager.name

Now script the model's reply — the kind of thing a model returns when nobody is constraining it. Prose on both sides, an unquoted key, single quotes, a comma-separated string where an array belongs, a number sent as text. The test kit replaces only the model, so the real output path runs on it.

import { runTest, user, model } from '@animahealth/adk/testing'

const scripted = `Reading it back: { urgency: 'URGENT', symptoms: "chest tightness, shortness of breath", followUpDays: "2" } — book them in.`

const triaged = await runTest(triager, [
  user('chest tightness since this morning and I cannot get a full breath'),
  model(scripted),
])

const shape = {
  text: triaged.result.output.text,
  value: triaged.output,
  assistantEvents: triaged.result.output.items.length,
  status: triaged.status,
}

shape

A run result carries an Output: text, value, items (every assistant event), and media. The raw sentence is still there in text — the schema adds value, it does not replace anything. The test kit's result is the same RunResult app.run returns, and its shorthand .output is that result's output.value.

Add a key and the parsed object is also written into session state, so the next agent in a sequence reads it as data rather than re-reading the transcript. When the app declares a session schema, naming that key alone — output: 'triage' — is shorthand for the same { key, schema, mode: 'native' }, with the schema taken from the declaration.

const recorder = app.agent({
  name: 'recorder',
  model: openai('gpt-5.6-luna'),
  context: [app.context.history()],
  output: { key: 'triage', schema: Triage },
})

const recorded = await runTest(recorder, [
  user('sore throat for two days, no fever'),
  model(`{ urgency: 'Routine', symptoms: "sore throat", followUpDays: 7 }`),
])

recorded.result.state

Step 2

The parser under it

Nothing about that was agent-specific. The output path calls the package's parser, and the parser is exported from the core entry: parse, parsePartial, createParser, parseJsonish, coerce. Run it directly on the same string and you get the same object.

A ParseResult is a union — value on the success branch, partial and errors on the failure branch — and both branches carry corrections and totalScore. A correction is a receipt: the path it touched, what it found, what it produced, and why. The score is the cost of getting there, so a high score is a signal to look at your prompt, not a failure.

import { parse } from '@animahealth/adk'

const parsed = parse(scripted, Triage)

const receipts = {
  parsed: parsed.success ? parsed.value : parsed.errors,
  score: parsed.totalScore,
  corrections: parsed.corrections.map((c) => ({
    path: c.path.join('.'),
    type: c.type,
    from: c.from,
    to: c.to,
  })),
}

receipts

One layer below is parseJsonish: text to a plain value, no schema involved. It strips code fences, finds JSON embedded in a sentence, closes unterminated strings and brackets, and accepts single quotes, unquoted keys and trailing commas. It does not throw and it does not report failure — given a sentence with no JSON in it, it hands the sentence back as a string. That is why a schema, not this layer, is what rejects bad output.

import { parseJsonish } from '@animahealth/adk'

const messyInputs = [
  '{"urgency": "urgent"}',
  '```json\n{"urgency": "urgent"}\n```',
  "{urgency: 'urgent', followUpDays: 2,}",
  'The answer is {"urgency": "urgent"} — hope that helps.',
  '{"urgency": "urgent", "symptoms": ["chest',
  'I would rather just chat.',
]

messyInputs.map((text) => {
  const repaired = parseJsonish(text)
  return { input: text, value: repaired.value, got: typeof repaired.value }
})

Step 3

Coercion, and switching it off

Valid JSON with the wrong types is the common case, so the schema stage coerces before it validates. Strings become numbers, booleans and dates; 'yes' is true; enum members match case-insensitively and across underscores and spaces; a comma-separated string becomes an array; a lone value becomes a one-element array; defaults fill absent keys. Every one of those lands as a correction.

import { coerce } from '@animahealth/adk'

const Reading = z.object({
  status: z.enum(['ok', 'high', 'low']),
  systolic: z.number(),
  tags: z.array(z.string()),
  reviewed: z.boolean(),
  notes: z.string().default('none'),
})

const coerced = coerce(
  { status: 'HIGH', systolic: '142', tags: 'urgent, recheck', reviewed: 'yes' },
  Reading,
)

coerced.success ? coerced.value : coerced.errors

Coercion and the text extraction above it are both configuration, and both default to on: createParser(schema, { coerceTypes, extractFromMarkdown }). Turn them off and the parser becomes JSON.parse plus schema.safeParse — strict, and useful when you would rather see the model's sloppiness than absorb it. The failure's stage says which: json when the text never parsed, coercion or validation when it parsed but did not fit.

import { createParser } from '@animahealth/adk'

const strict = createParser(Triage, { coerceTypes: false, extractFromMarkdown: false })

const refused = {
  onProse: strict.parse(scripted).errors,
  onCleanJsonWrongTypes: strict.parse('{"urgency":"urgent","symptoms":["cough"],"followUpDays":"2"}')
    .errors,
}

refused

Step 4

When nothing valid comes back

If the parser cannot produce a value the schema accepts — and cannot rescue a partial object that does — the run throws OutputParseError rather than handing you an output.value you would have to re-check. Script a model that refuses to answer in JSON and catch it.

let caught: unknown

try {
  await runTest(triager, [
    user('how are you today?'),
    model('I would rather just chat, thanks.'),
  ])
} catch (error) {
  caught = error
}

caught instanceof Error ? { name: caught.name, message: caught.message } : caught

Match on error.name, not instanceof. The OutputParseError class is exported from the core entry and carries rawOutput, schema, parseErrors, partial and corrections where it is thrown — but an error that crosses a run's event channel is reconstructed on the far side with its name and message preserved and its own fields gone. The package's own retry logic checks both for that reason.

That name is what app.ask(prompt, { schema }) retries on: a re-run budget that defaults to two when a schema is set and zero when it is not. Only a parse error is retried — a provider or transport error surfaces immediately, because re-asking cannot fix it.

Step 5

Native, prompt, and a real model

mode decides where the schema is enforced, and defaults to 'native': the adapter sends the schema to the provider as a response format, so the model is constrained before it writes a token. mode: 'prompt' withholds it, leaving the schema to your own prompt — which is where ctx.outputSchema comes in. It is the schema rendered as compact text for a system message. This cell asks for it, then reads back the system event the renderer produced, so you can see exactly what the model was told.

let rendered: string[] = []

const narrator = app.agent({
  name: 'narrator',
  model: openai('gpt-5.6-luna'),
  context: [
    app.context.system((ctx) => `Reply with JSON matching:\n${ctx.outputSchema}`),
    app.context((ctx) => {
      rendered = ctx.events.flatMap((e) => (e.type === 'system' ? [e.text] : []))
      return ctx
    }),
    app.context.history(),
  ],
  output: { schema: Triage, mode: 'prompt' },
})

await runTest(narrator, [user('chest tightness since this morning'), model(scripted)])

rendered

Now the real thing. Same agent as step 1, same schema, an actual model on the other end — and because its mode is the default, the schema goes to the provider as a response format. The parser still runs on whatever comes back; native mode makes its job easy rather than unnecessary. Edit the message and run it again.

const live = await app.run(
  triager,
  'Since last night: fever of 39, a stiff neck, and the light is hurting my eyes.',
)

live.output.value

Native mode wants an object schema: a top-level array or scalar is still parsed and validated on the way out, it is not sent to the provider as a format. Either way the choice is recorded — a model_start event names the output schema its call was rendered with, so an audit of a past run can tell a free-text turn from a structured one without replaying it. This last cell reads that back off the scripted run from step 1, so it needs no key.

triaged.events.flatMap((event) =>
  event.type === 'model_start'
    ? [{ agent: event.agentName, outputSchema: event.outputSchema }]
    : [],
)

Where this goes next: a typed value is what an assertion should read, so Testing agents without a model checks a run's output rather than its prose. And the same field is what makes app.ask(prompt, { schema }) hand back a parsed object instead of text — see Many agents.

Step 1

They are already on the app

app.tools carries the three factories, so the common case needs no import beyond the one you already have. Each takes a config object and returns a tool you put in an agent's tools array — the same FunctionTool app.tool returns. Building one touches no network and starts no browser: everything happens when the model calls it.

Every cell on this page runs with no key. The model's turns are scripted by the test kit, and the web tools themselves execute — against stand-ins you can read, so nothing here depends on a live site being up.

import { adk } from '@animahealth/adk'

const app = adk()

const pageFetcher = app.tools.fetchPage()
const screenshotter = app.tools.takeScreenshot({ maxTargets: 4 })

// A description is prompt, and config writes part of it: maxTargets above lands in the sentence
// the model reads before deciding.
const contracts = [pageFetcher, screenshotter].map((tool) => ({
  name: tool.name,
  description: tool.description,
}))

contracts

The @animahealth/adk/web subpath exports the same three factories in their ToolSpec form, which builds the same tool; reach for the subpath when you also need what only it exports: the SerperProvider class, the pipeline and result types, and the standalone helpers (fetchPagesBatch, screenshotPage, screenshotPages, closeBrowser).

One thing these are not: a provider's own hosted search. That runs inside the model provider and has no execute of yours; the ADK models it separately as a provider tool. Everything on this page is a function tool your process runs.

Step 2

webSearch, and the seam under it

The model sees a tool called web_search that takes a query and, when you allow it, a country code. The result is one field: results, an array of rows in the provider's ranking order.

type SearchRow = {
  title: string
  url: string
  snippet: string
  position: number
  date?: string
  content?: string // only when autoFetch pulled the page in
}

Where those rows come from is a SearchProvider: a name and a search(query, options). Pass one as provider and the tool is yours — an internal index, a cached corpus, a different search API. Omit it and the tool builds a SerperProvider the first time it searches, reading SERPER_API_KEY then. Building the tool needs no key; running it does — so a missing key surfaces on the first search, not at wiring time.

The cell below runs the real web_search tool with a stand-in provider, so it needs no key and makes no request. Only the provider is fake — the tool, its schema, the agent, and the ledger are the shipped ones. Watch what the tool hands the provider: the config you set becomes the provider's options.

import { openai } from '@animahealth/adk/openai'
import { findEventsByType, model, runTest, user } from '@animahealth/adk/testing'

// A stand-in for the search API. Real shape, invented rows — it echoes the options it was handed
// so you can see what the tool's config actually does.
const localIndex = {
  name: 'stand-in',
  search: async (query: string, options?: { numResults?: number; searchType?: string }) => [
    {
      title: `stand-in row for "${query}"`,
      url: 'https://example.com/adk',
      snippet: `asked for ${options?.numResults} ${options?.searchType} results`,
      position: 1,
    },
  ],
}

const searchTool = app.tools.webSearch({
  numResults: 3,
  searchType: 'news',
  provider: localIndex,
  // The country field leaves the schema the model is shown, and a country sent anyway is
  // stripped before execute sees the arguments.
  allowCountryOverride: false,
})

const researcher = app.agent({
  name: 'researcher',
  model: openai('gpt-5.6-luna'),
  context: [app.context.system('Search before you answer.'), app.context.history()],
  tools: [searchTool],
})

const searchRun = await runTest(researcher, [
  user('What has the ADK shipped lately?'),
  model({ toolCalls: [{ name: 'web_search', args: { query: 'anima adk release' } }] }),
  model('Here is what the search turned up.'),
])

const searched = findEventsByType(searchRun.events, 'tool_result')[0]?.result

searched

The rest of the config is a short list.

• numResults (default 10), searchType ('web', 'news', or 'images', default 'web'), and country are passed to the provider, which decides what to do with them.
• allowCountryOverride (default true) decides whether country is in the schema at all. A config country is the fallback when the model does not send one.
• autoFetch follows the top autoFetchTop results (default 3) with the fetch machinery of the next section and copies each page's markdown onto that row's content. autoFetchRender, proxy, and pipelines steer those fetches. It is one tool call and several page loads — budget for it.

Wiring the shipped provider is two lines, and the key can come from your own config rather than the environment.

import { SerperProvider, webSearch } from '@animahealth/adk/web'

// Constructing the provider yourself reads SERPER_API_KEY when the argument is omitted, and a
// missing key throws on this line rather than on the first search.
const search = app.use(webSearch({ provider: new SerperProvider(process.env.SEARCH_KEY) }))

Step 3

fetchPage, and the seam under it

One tool, three kinds of thing at the other end of a URL. An HTML page is reduced to article markdown — Readability picks the content, Turndown renders it. A PDF is truncated to maxPdfPages (default 10) and handed over as a document the model can look at. An image comes back as an image, scaled to fit 1280px. The kind is decided by the response's content-type, falling back to the URL's extension.

The model passes urls — one string or an array, capped at maxUrls (default 20) — and optionally includeSelectors, which annotates the markdown with [@selector] markers naming elements that can be screenshotted later. You get one entry per URL, in order.

type FetchedPage = {
  success: boolean
  url: string
  title?: string
  content?: string // markdown, for HTML pages
  wordCount?: number
  httpStatus?: number
  error?: 'timeout' | 'blocked' | 'not_found' | 'network_error' | 'api_error' | 'missing_dependency'
  errorMessage?: string // detail for the failure, e.g. which packages to install
  pipeline?: string // set by the pipeline that answered, if one did
  raw?: unknown // a pipeline's structured payload, if it supplied one
  mediaIndex?: number // this entry's PDF or image, by position — see the next section
}

A failure is never an exception here: the entry comes back with success: false and an error from that union, and the model reads it alongside the entries that worked. The rest of the config is timeout (default 30s per URL), concurrency (default 5), render, proxy, includeSelectors, and pipelines.

render: true is the escape hatch for pages that are empty without JavaScript: the fetch goes through a real browser instead of fetch. It runs on the shared browser of step 5, and it is the only fetch path a proxy applies to.

A FetchPipeline is the seam: a name, the patterns it claims, and a fetch. Pipelines are consulted before the network, in order, and the first one whose pattern matches and whose result has success: true wins. A pipeline that returns success: false is treated as having declined, and the ordinary fetch runs anyway — so a pipeline that exists to refuse a URL must succeed at refusing it.

import { fetchPage } from '@animahealth/adk/web'

const noInternalHosts = {
  name: 'internal-hosts',
  patterns: [/\.internal\.example\.com/],
  // success: true — this is the answer, not a failed attempt. Returning false would fall through
  // to the real fetch and defeat the point.
  async fetch(url: string) {
    return {
      success: true,
      url,
      title: 'Blocked',
      content: 'Internal hosts are not readable from here. Ask the platform team instead.',
    }
  },
}

const guardedFetch = app.use(fetchPage({ pipelines: [noInternalHosts] }))

Step 4

How pixels reach the model

A tool result is JSON, and a PDF is not. The ADK's convention for that is one reserved key: a tool may return __media alongside its result, and the runtime lifts it off before the result is recorded. The result the model reads never contains it; the tool_result event carries it in a sibling field, media, and the provider serializer attaches those parts to the tool's answer — an image part for an image, a file part for a document.

fetch_page and take_screenshot both use it, which is why an entry names a mediaIndex rather than carrying bytes. The cell below runs the real fetch_page tool with a pipeline that answers locally, so the only invented thing is the payload the pipeline hands back.

// A pipeline that claims one URL pattern and answers it from memory: no network, no jsdom, no
// browser. Where `media` sits here, the real tool puts the bytes it downloaded.
const localPipeline = {
  name: 'stand-in',
  patterns: [/example\.com\/report/],
  fetch: async (url: string) => ({
    success: true,
    url,
    title: 'Q3 report',
    content: '# Q3 report\n\nRevenue held flat.',
    wordCount: 6,
    pipeline: 'stand-in',
    media: { type: 'document' as const, mimeType: 'application/pdf', data: 'JVBERi0xLjQK' },
  }),
}

const reportFetcher = app.tools.fetchPage({ pipelines: [localPipeline] })

const reader = app.agent({
  name: 'reader',
  model: openai('gpt-5.6-luna'),
  context: [app.context.system('Read the page before summarising it.'), app.context.history()],
  tools: [reportFetcher],
})

const fetchRun = await runTest(reader, [
  user('Summarise https://example.com/report'),
  model({ toolCalls: [{ name: 'fetch_page', args: { urls: 'https://example.com/report' } }] }),
  model('Revenue held flat in Q3.'),
])

const fetched = findEventsByType(fetchRun.events, 'tool_result')[0]

const carried = {
  // What the model reads as the call's result: no bytes, just a pointer.
  result: fetched?.result,
  // What travels beside it. Printed as a summary — the data is base64.
  media: fetched?.media?.map((part) => ({
    kind: part.type,
    describes: part.source.type === 'base64' ? part.source.mimeType : part.source.url,
  })),
}

carried

Step 5

takeScreenshot and its one browser

Each target is a url and an optional CSS selector; the model may pass one target or an array of up to maxTargets (default 10). A selector captures that element — and if it matches nothing visible, the capture falls back to the viewport rather than failing. Without a selector, fullPage (default true) decides between the whole scrollable page and the viewport. Images are capped at 1280px on both axes, whatever maxWidth and maxHeight ask for.

Results follow the same split as fetch_page: a small entry per target, and the pictures on media.

type Shot = {
  success: boolean
  url: string // where the page ended up, after redirects
  selector?: string
  title?: string
  width?: number
  height?: number
  error?: string
}

maxTargets lives in the schema rather than in a check inside your code, so an over-long request is rejected at the border and the model is told why. The tool built in step 1 allows four.

const target = (n: number) => ({ url: `https://example.com/${n}` })

const border = {
  one: screenshotter.schema.safeParse({ targets: target(1) }).success,
  four: screenshotter.schema.safeParse({ targets: [1, 2, 3, 4].map(target) }).success,
  five: screenshotter.schema.safeParse({ targets: [1, 2, 3, 4, 5].map(target) }).success,
  withSelector: screenshotter.schema.safeParse({
    targets: { url: 'https://example.com', selector: 'main.report' },
  }).success,
}

border

Two operational facts about the browser underneath. It is a process-wide singleton: the first launch wins, so a proxy or a headless flag on a later call is ignored until the browser is closed. And it keeps the process alive — a script that screenshots and exits should call closeBrowser(). At most five browser operations run at once, across every tool sharing that browser; a call with more targets than that starts them all and they queue.

import { closeBrowser, screenshotPage } from '@animahealth/adk/web'

// The same capture the tool performs, callable directly — useful in a script or a test.
const shot = await screenshotPage('https://example.com', { selector: 'main', timeout: 15000 })

await closeBrowser() // otherwise the process does not exit

URLs that end in a download extension (.pdf, .zip, and friends) are refused before a page is opened, with an error saying so. Send those to fetch_page, which turns a PDF into something the model can read.

Step 6

Keys, packages, proxies

These tools are the ADK's only paid, installed, network-facing surface. Everything they need is an optional peer dependency, imported the moment it is needed and not before — so a dependency you skipped costs you nothing until a model calls the path that wants it, and then it costs you that call.

A throw out of a web tool is not a crash. It is the tool failure contract from Tools: the exception becomes the tool_result event's error, the model reads it, and the run continues. That is why these errors are written as instructions — the audience for "run npx playwright install" is a language model deciding what to do next, and it will tell your user.

Next

Tools you didn't write

Search, fetch, and screenshot are three tools someone else wrote and you configured. The general case of that is MCP: a server hands your agent tools it discovers at connect time, with the same schemas and the same ledger. That is Tools you didn't write.

Step 1

Declaring a server spawns nothing

app.mcp.server(config) registers a server on the app and hands you a handle. It does not spawn a process, open a socket, or list a single tool. Most of this page runs here because declaring is inert — the connection is deferred until an agent needs the tools, and section 6 is where that deferral comes due.

import { adk } from '@animahealth/adk'

const app = adk({ name: 'mcp-tour' })

// stdio: the ADK spawns this command and speaks MCP over its stdin/stdout.
const files = app.mcp.server({
  name: 'files',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/workspace'],
  cacheToolsList: true,
})

// HTTP: no child process, a URL. `authorization` is the raw token — the client sends the
// `Authorization: Bearer <token>` header for you, so do not write the word Bearer yourself.
const issues = app.mcp.server({
  name: 'issues',
  url: 'https://example.com/mcp',
  authorization: 'a-token-that-is-not-real',
  transport: 'http',
})

const declared = {
  kind: files.kind,
  name: files.name,
  connected: files.isConnected(),
  state: files.getState(),
  registered: app.mcp.servers().map((server) => server.name),
  sameHandleTwice: app.mcp.get('issues') === issues,
}

declared

Three things to take from that object. A server's kind is 'mcp_server', which is what lets it sit in an agent's tools array beside your own functions. Its state starts disconnected with no toolCount, because nothing has been listed yet. And registration is keyed by name: declaring the same name twice returns the handle you already have, so module-level declaration in two files does not give you two child processes.

A config must carry exactly one of command and url. Neither or both is a build-time throw, not a surprise at first use.

const rejected = ['neither', 'both'].map((shape) => {
  try {
    app.mcp.server(
      shape === 'neither'
        ? { name: `bad-${shape}` }
        : { name: `bad-${shape}`, command: 'npx', url: 'https://example.com/mcp' },
    )
    return { shape, error: null }
  } catch (error) {
    return { shape, error: error instanceof Error ? error.message : String(error) }
  }
})

rejected

Step 2

stdio, HTTP, SSE — and how one is chosen

The transport is decided by the config. command means stdio, always. url means a network transport, and then transport picks between 'http' (streamable HTTP) and 'sse'. Omit transport with a url and the client tries HTTP first, falls back to SSE, and — if both fail — reports the HTTP error, because that is the one you probably meant to succeed.

The fields each side reads:

• stdio — command, args, cwd, and env. Supply env and the child gets your whole process.env with your entries merged over it; omit it and the ADK passes nothing, leaving the transport to pick its own default environment. If a server needs a token, put the token in env rather than assuming inheritance.
• HTTP and SSE — url, headers, and authorization. authorization is a convenience that sets one header; anything else (an API key header, a tenant id) goes in headers.
• Both — timeout in milliseconds, defaulting to 30 000. It is per operation, not per server: connecting, listing tools, and each tool call get their own budget.

Step 3

What the model ends up seeing

An MCP server goes in tools, where a function tool goes. It stays a server there — the array holds one entry, not thirty — and it is expanded into real tools once per turn, before the first model call.

import { isMCPTool, isFunctionTool } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'
import { z } from 'zod'

const recordDecision = app.tool({
  name: 'record_decision',
  description: 'Write a decision to the audit log',
  schema: z.object({ note: z.string() }),
  execute: (ctx) => ({ recorded: ctx.args.note }),
})

const librarian = app.agent({
  name: 'librarian',
  model: openai('gpt-5.6-luna'),
  context: [app.context.system('Read the files before answering.'), app.context.history()],
  tools: [files, recordDecision],
})

// Three kinds can sit in `tools`, and the ADK tells them apart by shape, not by registration.
const declaredTools = librarian.tools.map((tool) => {
  if (isMCPTool(tool)) return { from: 'mcp server', name: tool.name }
  if (isFunctionTool(tool)) return { from: 'app.tool', name: tool.name }
  return { from: 'provider', name: tool.type }
})

declaredTools

At expansion time each tool the server advertises becomes an ordinary FunctionTool, and three transformations happen to it. Its name is prefixed mcp_<server>_<tool> — which is what keeps two servers' identically named tools apart, and the reason to keep the server name short, since it rides on every tool name the model reads. Its description passes through unchanged, or becomes MCP tool: <name> if the server offered none. And its JSON Schema is converted to a Zod schema: required properties stay required, optional ones become nullable and optional, description survives as .describe(), and the object is .strict() so an invented argument is rejected at the border.

So a server advertising this — the MCP wire format, not ADK —

{
  name: 'read_file',
  description: 'Read the complete contents of a file',
  inputSchema: {
    type: 'object',
    properties: {
      path: { type: 'string', description: 'Absolute path to the file' },
      encoding: { type: 'string' },
    },
    required: ['path'],
  },
}

reaches the model as this:

{
  name: 'mcp_files_read_file',
  description: 'Read the complete contents of a file',
  schema: z
    .object({
      path: z.string().describe('Absolute path to the file'),
      encoding: z.string().nullable().optional(),
    })
    .strict(),
}

When the model calls it, the arguments cross that schema, the client calls the server, and the reply is unwrapped before the model sees it. A single text block is parsed as JSON when it parses and handed over as a string when it does not; a single non-text block is passed through as-is; several blocks arrive as an array; none at all becomes { success: true, message: 'Operation completed with no output' }. If the server answers with isError, the tool throws with the server's own text — and from there it is the ordinary tool failure contract: a tool_result carrying an error, read by the model, run intact.

Step 4

Only these, never those

A general-purpose MCP server hands you everything it has, including the destructive half. Two filters trim it, and they compose: server.only([…]) keeps a list, server.exclude([…]) drops one. Both return a new server sharing the original's connection, so filtering costs no extra process. The same lists can be given up front as includeTools and excludeTools in the config.

const readOnly = files.only(['read_file', 'list_directory', 'search_files'])
const noDelete = files.exclude(['delete_file', 'move_file'])

const filtering = {
  derivedAreNewHandles: readOnly !== files && noDelete !== files,
  registryUnchanged: app.mcp.servers().map((server) => server.name),
  configIsTheOriginalObject: readOnly.config === files.config,
  configIncludeTools: readOnly.config.includeTools ?? null,
}

filtering

The last two lines matter: a derived server keeps the config object you passed to app.mcp.server, so .config.includeTools is not where .only() writes its list. Read the filter from the code that built the handle, not from the config. The rules themselves are short — .only() replaces the keep-list, .exclude() adds to the drop-list, and exclusion is applied last, so a name in both lists is dropped.

Filtering is client-side: the server is still asked for its full inventory and the trimming happens before the tools are built. It shapes what the model can reach, and it is the right first move on any server you did not write. It is not a permission boundary — the credentials you handed the server still are. For a confirmation step, wrap the risky operation in your own tool with a yieldSchema and let a human answer; that is Stopping to ask.

Step 5

Resources and prompts are context, not tools

MCP servers also publish resources (documents addressed by URI) and prompts (named, parameterised message templates). Neither is something a model calls. Both become context renderers, so they go in an agent's context array alongside app.context.system and app.context.history.

const readme = files.resource('file:///workspace/README.md')
const houseStyle = files.prompt('code-review', { language: 'typescript' })

const reviewer = app.agent({
  name: 'reviewer',
  model: openai('gpt-5.6-luna'),
  context: [
    app.context.system('Review the diff against the project README.'),
    readme,
    houseStyle,
    app.context.history(),
  ],
  tools: [readOnly],
})

const contextShape = {
  renderers: reviewer.context.length,
  resourceIsARenderer: typeof readme === 'function',
  promptIsARenderer: typeof houseStyle === 'function',
}

contextShape

A resource is fetched and appended as one system event reading [Resource: <uri>] then the text — so it is text or nothing: a binary resource has no text and contributes nothing. A prompt is fetched and its messages are appended as user and assistant events, which is how a server ships a worked example rather than an instruction.

And both fail open. If the fetch throws, the renderer logs a warning and returns the context untouched; the turn proceeds without that document. This is the opposite of the tools path, which fails the turn — the asymmetry in the next section — and it means a missing resource degrades an agent rather than stopping it. If a document must be there, read it yourself with await server.readResource(uri) and decide what to do when it is not.

The lower-level pair sits underneath: server.readResource(uri) returns { uri, mimeType, text, data } (data being a decoded Buffer for a blob), and server.getPrompt(name, args) returns { messages }. server.resourceDefinitions() and server.promptDefinitions() list what a server offers, the way server.toolDefinitions() lists its tools.

Step 6

Connect, fail, reconnect, close

Connection is lazy: the first turn of an agent carrying an MCP server connects it, because expanding the server into tools has to list them. await app.mcp.connect() moves that cost to startup, warming every registered server at once — and it never throws. Failures are collected, warned about, and swallowed, so one dead server cannot stop your process from booting. The state is where you find out.

Run the cell. It takes a few seconds — a connection is attempted three times with randomized backoff before it is given up on — and then both servers report the same thing, because this page is a browser tab: there is no process to spawn npx in and no @modelcontextprotocol/sdk to load. That is what you get here, and it is the same shape you would read on your own machine when a server is misconfigured.

await app.mcp.connect()

const afterWarmup = app.mcp.servers().map((server) => ({
  name: server.name,
  ...server.getState(),
}))

afterWarmup

Now the asymmetry that matters in production. app.mcp.connect() swallowing a failure does not make the failure harmless — it defers it. The tools are needed at the top of a turn, and if the server cannot be reached then, the connection error is thrown out of the run. Not a tool_result with an error; a rejected promise from app.run. The same agent, the same dead server — and the same few seconds, because the failed warm-up left nothing cached to reuse:

import { runTest, user, model } from '@animahealth/adk/testing'

let turnFailure = ''
try {
  await runTest(librarian, [user('What is in the README?'), model('It is a project readme.')])
} catch (error) {
  turnFailure = error instanceof Error ? error.message : String(error)
}

turnFailure

So: a warm-up call tells you whether a server is reachable, and server.getState() or await server.healthCheck() tells you which one is not. Check them at boot. An agent whose MCP server is down does not degrade — it stops.

Once connected, the client keeps itself alive without your help:

• Reconnect. An operation that fails with a connection-shaped error — EPIPE, ECONNRESET, ECONNREFUSED, or a message about being closed, disconnected, or not connected — reconnects and retries once. Other errors are yours to see.
• Caching. Tools are listed once per turn unless you set cacheToolsList: true, which reuses the first listing for the life of the connection. On a stdio server that is a round-trip to a child process on every turn, so set it — and know it is a real cache: a server that gains a tool while connected will not be noticed until it reconnects. cacheResourcesList and cachePromptsList do the same for the other two listings.
• Shutdown. await app.mcp.disconnect() closes every registered server and clears its caches; await app.close() does that and closes the session store. Child processes are also cleaned up on beforeExit, SIGTERM, and SIGINT, so a Ctrl-C does not leave an npx behind.

Step 7

The whole thing, on your machine

Everything above ran here. This last piece cannot: it needs a Node process, an OpenAI key, and one peer dependency — npm install @animahealth/adk @modelcontextprotocol/sdk. The MCP SDK is an optional peer, which is why importing the ADK does not drag it in, and why every failure in this page's cells says it is missing. Copy this into a file and run it.

import { adk } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'

const app = adk({ name: 'file-reader' })

const files = app.mcp.server({
  name: 'files',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', process.cwd()],
  cacheToolsList: true,
})

const agent = app.agent({
  name: 'librarian',
  model: openai('gpt-5-mini'),
  context: [
    app.context.system('Answer from the files. Read before you answer.'),
    app.context.history(),
  ],
  tools: [files.only(['read_file', 'list_directory', 'search_files'])],
})

// Warm up first, so a broken server is a startup error and not a mid-conversation one.
await app.mcp.connect()
console.log(files.getState())
console.log((await files.toolDefinitions()).map((tool) => tool.name))

const run = await app.run(agent, 'What does this project do? Read the README.')
console.log(run.output.text)

await app.close()

That is the whole surface — and once a server is declared, filtered, and warmed, the rest of the ADK cannot tell the difference between its tools and the ones you wrote by hand.

Step 1

An embedder and an index

A memory needs a model (anything satisfying Embedder: a dimensions count, an optional modelName, and an embed(texts) that returns one vector per text), an index, and a collection name. The optional metadata Zod schema types every read and write below and validates on the way in.

The embedder here is a stand-in built in the page: it hashes each word into one of 64 buckets and counts them, so a vector is a pure function of its text — no key, no network, identical output on every run. That makes it reproducible rather than good. It measures word overlap, not meaning: flu and influenza land in unrelated buckets. In production you pass voyage(name, { dimensions }) from @animahealth/adk/voyage, or any other object satisfying Embedder, and nothing else on this page changes.

import { memory, inMemoryIndex } from '@animahealth/adk'
import type { Embedder } from '@animahealth/adk'
import { z } from 'zod'

const DIMENSIONS = 64

// A real embedder calls a model. This one hashes words into buckets — deterministic, offline,
// and lexical: it can only see the words two texts share.
const hashEmbedder: Embedder = {
  dimensions: DIMENSIONS,
  modelName: 'hash-64',
  async embed(input) {
    return {
      model: 'hash-64',
      embeddings: input.map((text) => {
        const vector = Array.from({ length: DIMENSIONS }, () => 0)
        for (const token of text.toLowerCase().match(/[a-z0-9]+/g) ?? []) {
          let bucket = 0
          for (const char of token) bucket = (bucket * 31 + char.charCodeAt(0)) % DIMENSIONS
          vector[bucket] += 1
        }
        return vector
      }),
    }
  },
}

const notes = memory({
  model: hashEmbedder,
  index: inMemoryIndex(),
  collection: 'clinic_notes',
  metadata: z.object({
    patient: z.string(),
    topic: z.enum(['symptom', 'medication']),
    day: z.number(),
  }),
})

const built = { collection: notes.collection, dimensions: hashEmbedder.dimensions }

built

inMemoryIndex() is a real VectorIndex that keeps its points in a Map — the same interface sqlite-vec, pgvector and Qdrant implement, so the code below is the code you keep when you swap it. Pass model: { index, query } instead of one embedder for asymmetric retrieval; the factory throws at construction if the two dimensions disagree.

Step 2

Write, then search

upsert takes one item or an array of { id, content, metadata }. It embeds the content for you, in batches of 128, and stores the text alongside the vector — so a match carries its content back and you need no second lookup in another database. Pass embedding yourself to skip the embed call for that item.

await notes.upsert([
  { id: 'n1', content: 'Sore throat and fever for three days.',
    metadata: { patient: 'ada', topic: 'symptom', day: 3 } },
  { id: 'n2', content: 'Throat pain worse when swallowing.',
    metadata: { patient: 'ada', topic: 'symptom', day: 4 } },
  { id: 'n3', content: 'Prescribed amoxicillin, 500mg three times daily.',
    metadata: { patient: 'ada', topic: 'medication', day: 4 } },
  { id: 'n4', content: 'Ankle sprain after a fall while running.',
    metadata: { patient: 'sam', topic: 'symptom', day: 1 } },
  { id: 'n5', content: 'Ibuprofen for the ankle swelling.',
    metadata: { patient: 'sam', topic: 'medication', day: 2 } },
])

const found = await notes.search('sore throat', { topK: 3 })

const ranked = {
  stored: await notes.count(),
  matches: found.matches.map((match) => ({
    id: match.id,
    score: Number(match.score.toFixed(2)),
    topic: match.metadata.topic,
    content: match.content,
  })),
}

ranked

A search returns { matches, embedding }: the matches, and the query vector it computed — hand that to a second index instead of paying to embed the same string twice. Each match is { id, score, content, metadata }, cosine-similarity ordered, and the metadata is typed by the schema from step 1 (match.metadata.topic is 'symptom' | 'medication', and a typo is a compile error).

Look at the third result. It shares no word with the query and still scores. Cosine similarity returns a number for every point in the collection, so a nearest-neighbour search always returns something — which is what the next section's minScore is for. The write path continues past upsert — reading by id, merging metadata, deleting, and paging without a query — and the typed interface behind all of it is Vector backends.

Step 3

Narrowing the search

Four options shape a search, and they compose. topK caps the results — every shipped backend defaults to 10. filter restricts which points are eligible. minScore drops weak matches. contains demands a literal substring of the stored content, case-insensitively — a keyword gate bolted onto the vector search, not a second query.

A filter is either shorthand — an object of key/value pairs, every one of which must match — or the structured form with must, should and must_not arrays of conditions. A condition tests one metadata key with match (equality), text.contains (substring), or range (gt/gte/lt/lte, numeric or lexicographic). normalizeFilter is the exported function that turns the first form into the second, and every backend receives the second.

const idsOf = (result: { matches: { id: string }[] }) =>
  result.matches.map((match) => match.id)

// Shorthand: every key must match.
const forSam = await notes.search('pain', { filter: { patient: 'sam' } })

// Structured: day 4 or later, and not a medication note.
const recentSymptoms = await notes.search('pain', {
  filter: {
    must: [{ key: 'day', range: { gte: 4 } }],
    must_not: [{ key: 'topic', match: { value: 'medication' } }],
  },
})

// A literal substring of the stored content, whatever the query vector says.
const mentioningAnkle = await notes.search('anything at all', { contains: 'ankle' })

// Same query as step 2, with the weak match cut off.
const confident = await notes.search('sore throat', { minScore: 0.3 })

const narrowed = {
  forSam: idsOf(forSam),
  recentSymptoms: idsOf(recentSymptoms),
  mentioningAnkle: idsOf(mentioningAnkle),
  confident: idsOf(confident),
}

narrowed

The same filter shape works on count, scroll and deleteByFilter. It is also where tenancy belongs: put the org id in the metadata and filter every search on it, so no query can reach another tenant's rows.

Step 4

Handing the search to an agent

notes.tool(config) returns an ordinary FunctionTool, so the agent gets recall the same way it gets any other capability. The tool's schema is fixed at one query string — the model writes the search, your config sets the policy: topK, minScore, a filter (or a function of state that returns one), and a render that formats the matches. The name defaults to memory_search. Only description is required — it is the whole instruction the model reads before deciding to call.

import { adk } from '@animahealth/adk'
import { runTest, user, model, getToolResults } from '@animahealth/adk/testing'

const app = adk({ name: 'clinic' })

const recall = notes.tool({
  name: 'recall_notes',
  description: 'Search this patient\'s past clinic notes.',
  topK: 2,
  filter: { patient: 'ada' },
})

const assistant = app.agent({
  name: 'clinic_assistant',
  model: { provider: 'openai', name: 'gpt-5.6-luna' },
  context: [app.context.system('Search the notes before answering.'), app.context.history()],
  tools: [recall],
})

// The script decides THAT recall_notes is called; the search itself really runs.
const test = await runTest(assistant, [
  user('What did Ada come in with?'),
  model({ toolCalls: [{ name: 'recall_notes', args: { query: 'sore throat' } }] }),
  model('Ada reported a sore throat and fever.'),
])

getToolResults(test.events)

The result is a string, because that is what a model reads. The default rendering tags each match with its id — [memory] (id="n1") — and separates them with a rule; pass render to produce your own, with the matches typed by your metadata schema. The filter did its work here: the model asked for "sore throat" and could not have reached Sam's notes whatever it asked, because the filter is config, not prompt.

Step 5

Two views of one record

One record often has more than one useful text: a clean summary to search, the raw transcript to read. variants gives a point one named vector per view — same id, same metadata, different embedding and different stored content. The first name in the array is the default, and memory.variant.<name> addresses the others.

That splits searching from returning. returning(name) keeps searching the current variant's vectors but hands back another variant's content — search the tidy summary, show the model the transcript. returning throws on a variant you did not declare; variant is a plain record, so the same typo there is undefined.

const cases = memory({
  model: hashEmbedder,
  index: inMemoryIndex(),
  collection: 'case_notes',
  variants: ['summary', 'transcript'],
})

// The memory itself is its first variant; the others hang off `.variant`.
await cases.upsert({ id: 'c1', content: 'Sore throat, fever, likely viral.' })
await cases.upsert({ id: 'c2', content: 'Ankle sprain, rest and ibuprofen.' })
await cases.variant.transcript.upsert({
  id: 'c1',
  content: 'It started Friday. My throat hurts and I had a fever on Saturday night.',
})
await cases.variant.transcript.upsert({
  id: 'c2',
  content: 'I rolled my ankle running on Sunday.',
})

const contentOf = (result: { matches: { id: string; content: string }[] }) =>
  result.matches.map((m) => [m.id, m.content])

const views = {
  summaries: contentOf(await cases.search('fever')),
  summarySearchTranscriptContent: contentOf(await cases.returning('transcript').search('fever')),
  transcriptSearch: contentOf(await cases.variant.transcript.search('rolled my ankle')),
}

views

The first two searches rank identically — same vectors, same query — and differ only in the text they carry back. The third searches the transcript vectors instead, and reorders: "rolled my ankle" is a phrase from a transcript, not from a summary. Writes are per-variant, and every backend's compliance suite pins the consequence: a search over one variant sees only the points written for it.

Step 6

Several kinds in one collection

Variants are views of one record. Slices are different kinds of record sharing one collection — problems, medications, letters — each with its own metadata schema, all searchable at once. Pass slices instead of metadata and the shape of the memory changes: writes go through memory.slice.<name>, which is where the typed metadata lives, and there is no top-level upsert to write an unlabelled point with.

const chart = memory({
  model: hashEmbedder,
  index: inMemoryIndex(),
  collection: 'chart',
  slices: {
    problem: { metadata: z.object({ onset: z.string() }) },
    medication: { metadata: z.object({ dose: z.string() }) },
  },
})

await chart.slice.problem.upsert({
  id: 'p1',
  content: 'Acute sore throat',
  metadata: { onset: '2026-03-01' },
})
await chart.slice.medication.upsert({
  id: 'm1',
  content: 'Amoxicillin for the throat infection',
  metadata: { dose: '500mg' },
})
await chart.slice.medication.upsert({
  id: 'm2',
  content: 'Ibuprofen as needed',
  metadata: { dose: '400mg' },
})

const everything = await chart.search('throat')
const medsOnly = await chart.slices(['medication']).search('throat')

const sliced = {
  everything: everything.matches.map((m) => ({ id: m.id, kind: m.kind, metadata: m.metadata })),
  medsOnly: medsOnly.matches.map((m) => m.id),
}

sliced

A cross-slice search returns one ranked list, and every match carries the kind it came from — a discriminated union, so narrowing on match.kind narrows match.metadata to that slice's schema. chart.slices(['medication']) takes a subset and keeps the union typed to it; chart.slice.medication searches exactly one. The kind also becomes the tag in the default tool rendering from step 4, so a model reading cross-slice results can tell a medication from a problem.

The seam

Where the vectors actually live

Everything above ran against inMemoryIndex() and vanishes when this tab closes. Nothing above mentions a backend, and that is the point: VectorIndex is nine methods and an optional close, and memory() is the only thing your code talks to. collectionSpec computes what a backend has to provision for a given config — without connecting to anything.

import { collectionSpec } from '@animahealth/adk'

collectionSpec({
  model: hashEmbedder,
  collection: 'case_notes',
  variants: ['summary', 'transcript'],
})

Which backend to pick, what that spec provisions, what each one costs, and how their filtered searches differ is Vector backends.

For a complete example with typed state, two agents, and approval/resume, test a workflow without model calls.

Step 1

A scripted turn

First, the agent under test. It is an ordinary agent — nothing about it knows it is being tested — with one tool that computes a price and one that stops to ask the guest a question. Build it once; every cell below runs it.

import { adk } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'
import { z } from 'zod'

const app = adk()

const quoteNights = app.tool({
  name: 'quote_nights',
  description: 'Quote the price of a stay',
  schema: z.object({ nights: z.number(), guests: z.number() }),
  execute: (ctx) => ({ total: ctx.args.nights * ctx.args.guests * 40 }),
})

// A tool with a `yieldSchema` and no `execute` stops the run and waits for an answer.
const askNight = app.tool({
  name: 'ask_night',
  description: 'Ask the guest which night they want',
  schema: z.object({ question: z.string() }),
  yieldSchema: z.object({ night: z.string() }),
  finalize: (ctx) => ({ night: ctx.input?.night ?? 'unknown' }),
})

const concierge = app.agent({
  name: 'concierge',
  model: openai('gpt-5.6-luna'),
  context: [app.context.system('Quote stays with the tools.'), app.context.history()],
  tools: [quoteNights, askNight],
})

concierge.name

That model: line names a real provider, and this page has no key — yet the next cell runs. runTest builds its own runner with a mock adapter registered for the provider, and a registered adapter beats the one the agent's model config would resolve. Nothing reaches the network, so you never have to keep a separate "test agent" in sync with the one you ship.

A test is the agent plus a list of steps. user(text) is a message in; model(text) is the reply the model would have produced. Edit the script and run again — the reply is whatever you say it is.

import { getLastAssistantText, model, runTest, user } from '@animahealth/adk/testing'

const greeting = await runTest(concierge, [
  user('Hi, are you open in March?'),
  model('We are — how many nights were you thinking?'),
])

getLastAssistantText(greeting.events)

model('plain text') is shorthand for model({ text: 'plain text' }), symmetric with user. The config form is what you reach for when a turn is more than words: a tool decision, a reasoning summary, a thrown error, a delay, a chunked stream. Section 4 lists every field.

Step 2

The mock replaces the model, not your code

This is the idea the kit rests on. Scripting { toolCalls: [{ name, args }] } decides that the tool is called and with what — it does not decide the answer. Your execute runs for real, against the arguments the script chose, and the number below is computed in this page by the tool you wrote in step 1.

import { getToolResults } from '@animahealth/adk/testing'

const quoted = await runTest(concierge, [
  user('Two nights for three of us — what does that cost?'),
  model({ toolCalls: [{ name: 'quote_nights', args: { nights: 2, guests: 3 } }] }),
  model('Two nights for three guests comes to 240.'),
])

getToolResults(quoted.events)

Two model steps for one question, because a tool-using turn is two model round-trips: one to decide the call, one to answer with its result. Change the arithmetic in the tool and this cell changes with it; change the second model line and it does not. That is the seam — the script owns the model's judgement, your code owns the answer.

Failure travels the same path: a tool that throws lands in the ledger as a tool_result carrying error, and the run continues — see guardrails and recovery.

Step 3

What the run left behind

Assertions read the event history, not a transcript. TestResult.events is an alias for the session ledger — see five primitives and one ledger.

import { getToolCalls } from '@animahealth/adk/testing'

const ledger = {
  status: quoted.status,
  iterations: quoted.iterations,
  calls: getToolCalls(quoted.events),
  events: quoted.events.map((event) => event.type),
  streamed: quoted.streamEvents.map((event) => event.type),
}

ledger

Read it left to right: the user's message, the invocation opening, a model_start/model_end pair for the decision, the tool_call and the tool_result your code produced, a second model pair for the reply, then the assistant text. iterations counts those two model steps. Everything a real run records, the scripted run records too.

events is the durable ledger; streamEvents is what a subscriber saw while the run was in flight — the same events without what the session already held, plus the deltas a chunked turn emits and the ledger never keeps. A scripted run cannot report cost. There were no tokens, so quoted.result.usage is undefined. Measure cost against a real model, on the streaming and cost page.

A TestResult also carries result — the whole untouched RunResult, for anything the aliases do not cover.

Four helpers cover most assertions, and each takes an event list: getLastAssistantText, getToolCalls, getToolResults, and findEventsByType(events, 'thought') for anything else. findStreamEventsByType is their counterpart over streamEvents, and collectStream drains a live stream into events plus result.

Step 4

The step vocabulary

Four step builders, and the runner walks them in order. user and model you have seen. input and result exist for the other direction: when the agent stops and waits, they are how the test answers it.

Now the pair in motion. ask_night yields, the run stops, the input step hands back a night, and finalize turns it into the tool's result — all inside one runTest call.

import { input } from '@animahealth/adk/testing'

const resumed = await runTest(concierge, [
  user('Book me a room'),
  model({ toolCalls: [{ name: 'ask_night', args: { question: 'Which night?' } }] }),
  input({ ask_night: { night: 'Friday' } }),
  model('Booked for Friday.'),
])

const waited = {
  status: resumed.status,
  events: resumed.events.map((event) => event.type),
  results: getToolResults(resumed.events),
}

waited

tool_yield, invocation_yield, tool_input, invocation_resume — the whole pause is in the ledger, which is what lets a sleeping agent be a database row. Delete the input line and run again: the test comes back with status yielded_tool, still waiting. Yielding tools have their own chapter, stopping to ask.

A model turn's config is a small, closed set:

Step 5

Stand-ins, failures, and the adapter underneath

Not every test needs a real agent. mockAgent(name, config?) — positional name first — returns an agent with no tools and a history renderer, useful as the neighbour in a multi-agent test or as the thing a router hands off to. Its config.responses are consumed before the script's model steps.

And failure is a step like any other. model({ error }) throws from inside the model call, so the runTest promise rejects — catch it, and assert on what your error handlers did.

import { mockAgent } from '@animahealth/adk/testing'

const triage = mockAgent('triage', { responses: [{ text: 'Escalating to a human.' }] })
const stubbed = await runTest(triage, [user('My booking vanished')])

let failure = 'the run did not fail'
try {
  await runTest(mockAgent('flaky'), [
    user('hello'),
    model({ error: new Error('429 rate limited') }),
  ])
} catch (thrown) {
  failure = thrown instanceof Error ? thrown.message : String(thrown)
}

const stubs = { stubbed: getLastAssistantText(stubbed.events), failure }

stubs

Underneath both is MockAdapter, and you can hold it yourself. An app built with adk({ adapters: { openai: mockAdapter } }) runs the ordinary app.run path — sessions, hooks, stores, everything the quickstart showed — with the model replaced. Use it to test the code around the agent rather than the agent's turns.

import { MockAdapter } from '@animahealth/adk/testing'

const scripted = new MockAdapter({
  responses: [
    { toolCalls: [{ name: 'quote_nights', args: { nights: 3, guests: 2 } }] },
    { text: 'Three nights for two is 240.' },
  ],
  defaultResponse: { text: 'the script ran out' },
})

const offline = adk({ adapters: { openai: scripted } })

const first = await offline.run(concierge, 'Three nights for two?')
const second = await offline.run(concierge, 'And a fourth night?')

const adapterRuns = { first: first.output.text, second: second.output.text }

adapterRuns

The second run prints the fallback: one adapter holds one cursor, and it keeps advancing across runs. When the responses are exhausted, defaultResponse answers — and its own default is the string Mock response, which is how an under-scripted test passes while asserting nothing. Set defaultResponse to something you would notice, or call scripted.reset() between runs.

Step 6

In your repo, with no credentials

Everything above is a plain async function call, so it drops into any runner. Nothing reads an environment variable, opens a socket, or asks for a key — so agent tests pass on a pull request from outside your org and on a laptop with no secrets. This block imports vitest, which this page's substrate does not serve, so it is shown rather than run.

import { describe, expect, it } from 'vitest'
import { getToolResults, model, runTest, user } from '@animahealth/adk/testing'

import { concierge } from './concierge'

describe('concierge', () => {
  it('quotes from the tool, not from the model', async () => {
    const outcome = await runTest(concierge, [
      user('Two nights for three of us?'),
      model({ toolCalls: [{ name: 'quote_nights', args: { nights: 2, guests: 3 } }] }),
      model('That comes to 240.'),
    ])

    expect(outcome.status).toBe('completed')
    expect(getToolResults(outcome.events)).toEqual([
      { name: 'quote_nights', result: { total: 240 } },
    ])
  })
})

The kit also ships vitest matchers — toHaveAssistantText, toHaveToolCall, toHaveToolResult, toHaveEventSequence, toHaveStatus, toHaveState, toHaveEvent, toBeUuid — registered by await setupAdkMatchers(). The helper-based assertions above need no setup at all.

One more piece of the kit these cells did not need: createTestContext(agent). Scripted turns prove behaviour; to score quality against a real model, go on to measuring agents.

Step 1

Define the working data once.

The availability tool proposes a slot. The booking tool waits for a typed approval before changing the booking state. Both tools use the schema declared on the app; their ctx.state fields are inferred from it. This example records a booking as a counter in memory, so it cannot book a real appointment.

import { adk } from '@animahealth/adk'
import { MockAdapter } from '@animahealth/adk/testing'
import { z } from 'zod'

const scripted = new MockAdapter()
const bookingApp = adk({
	name: 'booking-demo',
	schema: {
		session: {
			request: z.string().default('Please find an appointment on Tuesday.'),
			slot: z.string().default(''),
			status: z.enum(['searching', 'proposed', 'booked', 'declined']).default('searching'),
			bookings: z.number().default(0),
		},
	},
	adapters: { openai: scripted },
})

const findSlot = bookingApp.tool({
	name: 'find_slot',
	description: 'Find an available appointment slot.',
	schema: z.object({}),
	execute: (ctx) => {
		ctx.state.slot = 'Tuesday 14:30'
		ctx.state.status = 'proposed'
		return { slot: ctx.state.slot }
	},
})

const bookSlot = bookingApp.tool({
	name: 'book_slot',
	description: 'Ask for approval to book the proposed slot.',
	schema: z.object({}),
	yieldSchema: z.object({ approved: z.boolean() }),
	execute: (ctx) => {
		if (!ctx.input?.approved) {
			ctx.state.status = 'declined'
			return { booked: false }
		}
		ctx.state.bookings += 1
		ctx.state.status = 'booked'
		return { booked: true, slot: ctx.state.slot }
	},
})

const toolNames = [findSlot.name, bookSlot.name]

toolNames

The cell prints the two tool names. Neither tool has executed yet.

Step 2

Share a slot without sharing the whole conversation.

The specialist reads the request from state and sees its own history. The booking assistant receives the proposed slot through typed state, plus its own history. It does not receive the specialist's conversation. A sequence runs the specialist first, then the booking assistant.

const availability = bookingApp.agent({
	name: 'availability',
	model: { provider: 'openai', name: 'scripted' },
	context: [
		bookingApp.context.system(({ state }) => `Find a slot for this request: ${state.request}`),
		bookingApp.context.history({ scope: 'invocation' }),
	],
	tools: [findSlot],
})

const coordinator = bookingApp.agent({
	name: 'coordinator',
	model: { provider: 'openai', name: 'scripted' },
	context: [
		bookingApp.context.system(({ state }) =>
			`Offer ${state.slot}. Use book_slot to request approval. Booking status: ${state.status}.`,
		),
		bookingApp.context.history({ scope: 'invocation' }),
	],
	tools: [bookSlot],
})

const bookingFlow = bookingApp.sequence({
	name: 'booking',
	runnables: [availability, coordinator],
})

bookingFlow.name

Step 3

Stop before the booking happens.

The script supplies the model's decisions. The runtime executes find_slot, writes its state, and yields when the coordinator calls book_slot. Expect yielded_tool, a proposed slot, and zero bookings.

scripted.reset()
scripted.setResponses([
	{ toolCalls: [{ name: 'find_slot', args: {} }] },
	{ text: 'The availability check found Tuesday 14:30.' },
	{ toolCalls: [{ name: 'book_slot', args: {} }] },
])

const pausedBooking = await bookingApp.run(bookingFlow, {
	input: {
		message: 'Please find an appointment on Tuesday.',
		initialState: { session: {} },
	},
})

const waitingBooking = {
	status: pausedBooking.status,
	slot: pausedBooking.state.slot,
	bookings: pausedBooking.state.bookings,
	waitingFor: pausedBooking.session.yieldedTools.map((tool) => tool.name),
}

waitingBooking

Step 4

Inspect the two model inputs.

The scripted adapter records the context it receives. Read the messages below: the coordinator knows the slot through its system message, without receiving the specialist's reply. The full session still records both agents' work.

const modelInputs = scripted.stepCalls.map(({ ctx }) => ({
	agent: ctx.agent.name,
	messages: ctx.events.flatMap((event) =>
		event.type === 'system' || event.type === 'user' || event.type === 'assistant'
			? [`${event.type}: ${event.text}`]
			: [],
	),
	tools: ctx.functionTools.map((tool) => tool.name),
}))

modelInputs

This view shows text messages and available tool names. The Context chapter also shows tool-call and tool-result messages, history scopes, and filters. Context selection controls model input, not access permissions.

Step 5

Supply the answer and inspect the result.

Keep approved true to book. To try rejection, rerun step 3, change approved to false, and run this cell again. Approval produces one booking; rejection leaves zero. The tool checks the decision in code.

const approved = true
const pendingBooking = pausedBooking.session.yieldedTools[0]
if (!pendingBooking) throw new Error('Run step 3 again to create a pending booking.')

pausedBooking.session.input.tool({
	callId: pendingBooking.callId,
	input: { approved },
})
scripted.setResponses([{ text: 'Your decision has been recorded.' }])

const finishedBooking = await bookingApp.run(bookingFlow, { session: pausedBooking.session })

const bookingOutcome = {
	status: finishedBooking.state.status,
	bookings: finishedBooking.state.bookings,
	changes: finishedBooking.session.events.flatMap((event) =>
		event.type === 'state_change' ? event.changes : [],
	),
}

bookingOutcome

The model's closing sentence is scripted. The booking count and state changes come from the tool that actually executed. Tests can assert on those outcomes; live evaluations measure whether a model makes the right decisions.

Continue building

Run it beyond this page.

This example keeps its session in browser memory. To survive a process exit, use a persistent store and commit the session. The Bookings sample demonstrates that boundary with SQLite and separate commands for asking and approving.

• Persist and resume the Bookings sample.
• Let a live model choose its tool calls.
• Install the package and build locally.
• Write deterministic tests or evaluate model behavior.
• Build a voice agent and evaluate its calls.

Step 1

A case, and the tools it must not really call

The agent under test is ordinary: one tool that reads, one tool that spends money. Nothing about it knows it is being evaluated. Build it once — every cell below scores this agent. Only the last cell on the page calls a real model, so the key box can stay empty until then.

import { adk } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'
import { z } from 'zod'

const app = adk()

const orderStatus = app.tool({
  name: 'order_status',
  description: 'Look up an order and how late it arrived',
  schema: z.object({ orderId: z.string() }),
  execute: (ctx) => ({ orderId: ctx.args.orderId, daysLate: ctx.args.orderId === 'A-1' ? 7 : 0 }),
})

// The dangerous one. Its execute is deliberately unreachable, so a run that reaches it is loud.
const issueRefund = app.tool({
  name: 'issue_refund',
  description: 'Refund an order. Moves real money.',
  schema: z.object({ orderId: z.string(), amount: z.number() }),
  execute: () => {
    throw new Error('the real refund gateway was called')
  },
})

const support = app.agent({
  name: 'support',
  model: openai('gpt-5.6-luna'),
  context: [
    app.context.system('Refund an order only if it arrived more than three days late. Check it first.'),
    app.context.history(),
  ],
  tools: [orderStatus, issueRefund],
})

support.name

Testing replaced the model and let your tools run. An eval moves the other seam too: toolMocks replaces a tool's execute, so a suite can exercise the refund path a thousand times without a thousand refunds. A mock is { execute }, and its signature is not a tool's: execute(args, ctx) takes the arguments first, where a real tool takes one ctx and reads ctx.args. Passing the real tool as the value instead lets it through untouched, which is what you want for a lookup with no side effects.

One case is one run plus the mocks it is allowed. app.evaluate takes a single case or an array; either way it answers with a suite result.

import { MockAdapter, type MockAdapterConfig } from '@animahealth/adk/testing'

// A fresh adapter per suite. One MockAdapter holds one cursor, so reusing it would make the
// second press of Run disagree with the first.
const offline = (responses: MockAdapterConfig['responses']) =>
  adk({
    adapters: {
      openai: new MockAdapter({ responses, defaultResponse: { text: 'the script ran out' } }),
    },
  })

const refundScript = [
  { toolCalls: [{ name: 'order_status', args: { orderId: 'A-1' } }] },
  { toolCalls: [{ name: 'issue_refund', args: { orderId: 'A-1', amount: 40 } }] },
  { text: 'Order A-1 was seven days late, so I have refunded 40.' },
]

const mocks = {
  order_status: orderStatus, // real: it only reads
  issue_refund: {
    execute: (args: unknown) => ({
      refunded: true,
      reference: `mock-${(args as { orderId: string }).orderId}`,
    }),
  },
}

const first = await offline(refundScript).evaluate({
  name: 'refunds a late order',
  runnable: support,
  input: 'Order A-1 turned up a week late. I want my money back.',
  toolMocks: mocks,
})

const outcome = {
  summary: first.summary,
  status: first.results[0].status,
  turns: first.results[0].turns,
  tools: first.results[0].events.flatMap((event) =>
    event.type === 'tool_result' ? [{ name: event.name, result: event.result }] : [],
  ),
}

outcome

The refund reference is mock-A-1, so the mock ran and the gateway did not. Delete the issue_refund entry and press Run again: toolMocks is strict, so a called tool with no entry throws inside the tool. That is an ordinary tool-phase error, and the default handler records it rather than propagating it — it lands in the ledger as a tool_result carrying an error that names the tool and prints the mock you should have written. Nothing escapes evaluate: the run answers the customer anyway, and the case still comes back passed.

Step 2

The metric is the question

A metric is a name and a function over the finished run: { name, evaluate(run) }, returning passed and optionally score, evidence, and data. It reads the ledger — run.session.events and run.session.state — because that is where everything the agent did already is. app.evaluate.metric is an identity helper that types the callback; it changes nothing at runtime.

import type { Event } from '@animahealth/adk'

const toolsCalled = (events: readonly Event[]) =>
  events.flatMap((event) => (event.type === 'tool_call' ? [event.name] : []))

const refundIssued = app.evaluate.metric({
  name: 'refund_issued',
  evaluate: (run) => {
    const called = toolsCalled(run.session.events)
    const passed = called.includes('issue_refund')
    return { passed, score: passed ? 1 : 0, evidence: [`called: ${called.join(' → ') || 'nothing'}`] }
  },
})

const refundDeclined = app.evaluate.metric({
  name: 'refund_declined',
  evaluate: (run) => {
    const refunds = toolsCalled(run.session.events).filter((name) => name === 'issue_refund')
    return { passed: refunds.length === 0, evidence: [`issue_refund calls: ${refunds.length}`] }
  },
})

// The invariant both cases owe: never refund without looking the order up first.
const checkedFirst = app.evaluate.metric({
  name: 'checked_first',
  evaluate: (run) => {
    const called = toolsCalled(run.session.events)
    const refundAt = called.indexOf('issue_refund')
    const lookupAt = called.indexOf('order_status')
    return {
      passed: refundAt === -1 || (lookupAt !== -1 && lookupAt < refundAt),
      evidence: [`order: ${called.join(' → ') || 'no tools'}`],
    }
  },
})

const questions = [refundIssued, refundDeclined, checkedFirst].map((metric) => metric.name)

questions

A metric that throws does not crash the suite: the runner catches it and records passed: false with the error as its evidence. Scores between 0 and 1 are averaged into the report; anything outside that range is carried but not averaged.

Four metric builders ship for the shapes you write most often. They live on the @animahealth/adk/eval subpath, which this page's substrate does not serve, so this block is shown rather than run — the cells above are the runnable form of the same contract.

import {
  eventCountMetric,
  eventSequenceMetric,
  stateMetric,
  timingMetric,
} from '@animahealth/adk/eval'

// How many events of a type match a filter?
eventCountMetric({
  name: 'refunded_once',
  eventType: 'tool_call',
  filter: (event) => event.name === 'issue_refund',
  assertion: (count) => count === 1,
})

// Did these events happen, in this order? (Other events in between are allowed.)
eventSequenceMetric({
  name: 'lookup_then_refund',
  sequence: [
    { eventType: 'tool_call', filter: (event) => event.name === 'order_status' },
    { eventType: 'tool_call', filter: (event) => event.name === 'issue_refund' },
  ],
})

// What did a state key end up as? (Replayed from the run's state_change events.)
stateMetric({
  name: 'case_closed',
  scope: 'session',
  key: 'closed',
  assertion: (value) => value === true,
})

// Was it fast enough?
timingMetric({
  name: 'answered_quickly',
  measure: 'time_to_first_assistant',
  assertion: (ms) => ms < 4000,
})

timingMetric's measure is a closed set: total_duration, time_to_first_assistant, time_to_first_tool_call, model_latency_total, model_latency_average, tool_execution_total, tool_execution_average. A measure it cannot compute — no matching events, missing timestamps — fails with that as its evidence rather than passing vacuously. The same subpath also ships codingDeltaMetric, for scoring a coding agent on the diff it produced rather than on its summary of the diff.

Step 3

A suite, and where its verdict comes from

Metrics attach in two places. Suite-level metrics in the options apply to every case — the invariants. Case-level metrics are added on top — the thing that case is about. Here one case must refund and one must not, and both owe the ordering invariant.

const declineScript = [
  { toolCalls: [{ name: 'order_status', args: { orderId: 'B-2' } }] },
  { text: 'Order B-2 arrived on time, so there is nothing to refund.' },
]

const refundCases = app.evaluate.cases([
  {
    name: 'refunds a late order',
    runnable: support,
    input: 'Order A-1 turned up a week late. I want my money back.',
    toolMocks: mocks,
    metrics: [refundIssued],
  },
  {
    name: 'leaves an on-time order alone',
    runnable: support,
    input: 'Order B-2 arrived on Tuesday as promised. Refund me anyway?',
    toolMocks: mocks,
    metrics: [refundDeclined],
  },
])

const suite = await offline([...refundScript, ...declineScript]).evaluate(refundCases, {
  metrics: [checkedFirst],
  concurrency: 1,
})

const scored = {
  summary: suite.summary,
  cases: suite.results.map((result) => ({
    name: result.name,
    status: result.status,
    metrics: result.metrics,
  })),
}

scored

app.evaluate.cases exists so a case array written in its own module is checked against the app's state schema at the point you write it, not the point you run it.

concurrency: 1 matters only here: one scripted cursor serves both cases. Against a real model the default of 64 applies.

A case's status is the run's outcome first, metrics second. If the run ended terminated, error, or aborted, that is the status and the metrics are decoration. Otherwise it is passed when every metric passed and failed when one did not — so a run that ends parked on a yield still passes, if what you asked about is true.

Step 4

The report

app.evaluate.report(options?) returns a function from a suite result to markdown: pass rate, per-metric rates with a mean of any 0–1 scores, then a Cases section that lists only the failures and their evidence. It is a pure function of the result — no rerun, no second pass over the model.

const markdown = app.evaluate.report({
  title: 'Refund suite',
  footer: (result) => `${result.results.length} cases in ${result.durationMs}ms`,
})(suite)

markdown

sections and renderCase customise the output when the audience is a reviewer rather than CI.

Each case result carries more than the report prints. run is the whole RunResult and events is its session ledger, so anything the test kit's helpers read, a failing case can be debugged with. turns counts the user messages in the run — one for a single-shot case, more once a simulated user is answering.

summary counts each of those across the suite as total, passed, failed, errors, terminated, aborted, timedOut. Only passed is good news; a suite that is 40% errors is not 60% healthy.

Step 5

Simulating the other side

Every case so far was one message in. Real behaviour needs a conversation, and a conversation needs someone on the other end. app.simulate is the loop app.evaluate runs each case through: run the agent, and while it is parked, answer it and run it again. A userAgent answers a message yield; a toolAgents entry, keyed by tool name, answers a yielding tool's question.

const chatSupport = app.agent({
  name: 'chat_support',
  model: openai('gpt-5.6-luna'),
  context: [app.context.system('Ask one question at a time.'), app.context.history()],
  tools: [],
  yields: true,
})

const customer = app.agent({
  name: 'customer',
  model: openai('gpt-5.6-luna'),
  context: [app.context.system('You are a customer chasing a refund. Answer briefly.'), app.context.history()],
  tools: [],
})

// Two agents interleaving: route by name so neither can eat the other's script.
const conversationAdapter = new MockAdapter({ defaultResponse: { text: 'the script ran out' } })
conversationAdapter.addResponses('agent:chat_support', [
  { text: 'Sorry about that — what is the order number?' },
  { text: 'Thanks. Was it more than three days late?' },
  { text: 'Then I can refund A-1 for you now.' },
])
conversationAdapter.addResponses('agent:customer', [{ text: 'A-1.' }, { text: 'Seven days late.' }])

const conversation = await adk({ adapters: { openai: conversationAdapter } }).simulate(chatSupport, {
  input: 'I want a refund.',
  userAgent: customer,
  maxTurns: 2,
})

const transcript = conversation.session.events.flatMap((event) => {
  if (event.type === 'user') return [`customer: ${event.text}`]
  if (event.type === 'assistant') return [`support: ${event.text}`]
  return []
})

const simulated = {
  status: conversation.status,
  stoppedBecause: conversation.status === 'terminated' ? conversation.terminationReason : undefined,
  transcript,
}

simulated

The customer's own turns are missing from that ledger on purpose: the simulated user runs in its own session, and only the message it produced crosses into the agent's. That is the whole trick — the agent under test cannot tell a simulated user from a real one, because it sees the same rows either way.

An agent with yields: true never completes on its own, so the loop needs a stop condition. maxTurns caps the exchanges, maxDuration caps the clock, and stateMatches stops as soon as the session state says the thing you were waiting for happened — { session: { refunded: true } }, with $exists, $eq, and $ne available for a key you want to test rather than match. Whichever fires, the result comes back terminated with the reason attached, and a case in a suite reports that status verbatim.

Two customisations sit either side of the loop. transform.prepareInput rewrites what the simulated user or tool agent is asked — by default the agent's last reply for a message yield, and the tool call as JSON for a tool yield. transform.processOutput rewrites what comes back, which is how a scripted answer table replaces a model entirely. A tool yield with no matching toolAgents entry also throws by name — but unlike a missing toolMocks entry, nothing records it. The throw escapes the loop, so simulate rejects and a case in a suite comes back error.

Step 6

Against a real model

Nothing above needed a key, and nothing above measured a model — a scripted adapter can only confirm the plumbing. Point the same cases at a real model and the suite starts answering the question it exists for: does this model, on this prompt, do the right thing? The mocks stay, so the refund gateway is still never called; only the model changes. Paste a key into the box at the top of the page and press Run.

const live = await app.evaluate(refundCases, {
  metrics: [checkedFirst],
  onCase: (result, done, total) => console.log(`${done}/${total} ${result.name}: ${result.status}`),
})

app.evaluate.report({ title: 'Refund suite · live' })(live)

Now the numbers mean something, including the money ones: each case result carries usage, and the report totals tokens and cost across the suite when the provider reported them. Edit the system prompt in step 1, press Run again, and watch the pass rate and the bill move together. Run it with repeat: 5 and the report groups the runs per case — a metric that passes four times out of five is the fact a single green run was hiding.

Step 7

In your repo

An eval suite is an async function call and a number, so it needs no runner of its own. This block imports node:process, which this page's substrate does not serve, so it is shown rather than run.

import process from 'node:process'

import { app } from './app'
import { refundCases } from './cases'
import { checkedFirst } from './metrics'

const result = await app.evaluate(refundCases, {
  metrics: [checkedFirst],
  repeat: 5,
  onCase: (caseResult, done, total) =>
    process.stdout.write(`\r${done}/${total} ${caseResult.name}`),
})

process.stdout.write(`\n${app.evaluate.report({ title: 'Refund suite' })(result)}\n`)

// The gate is yours: `evaluate` reports, it does not exit. A CI suite that never fails the
// build is a dashboard, not a gate.
const bad = result.summary.failed + result.summary.errors + result.summary.timedOut
process.exit(bad > 0 ? 1 : 0)

Teams forget that last line. app.evaluate returns a result and never throws on a failed metric, because a local exploration run wants the report more than it wants an exception. Anything blocking a merge has to read summary and decide.

Two boundaries. Deterministic behaviour belongs in scripted tests, not here: an eval that a script could have answered is a slow, expensive test. And spoken conversations have their own surface: app.evaluate.voice, with recordings, transcripts, and turn timings — see voice agents.

Where this goes next: guardrails and recovery for the failures a suite keeps finding, and streaming and cost for the usage numbers the live report totalled.

Step 1

One hook, nine lifecycle points

A Hook is a plain object with optional methods: onEvent and onStep observe, beforeAgent/afterAgent, beforeModel/afterModel and beforeTool/afterTool wrap each phase, and afterTurn runs inside the commit boundary. It is one interface rather than a split observer and interceptor because the concerns that need both — rate limits, budget caps, redaction — need them in the same place. Implement the methods you want; the rest are undefined and cost nothing.

The setup uses a MockAdapter to script provider responses and record model calls. Tools and hooks execute in the real ADK runtime. See Testing for the test utilities.

import { adk } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'
import { MockAdapter } from '@animahealth/adk/testing'
import { z } from 'zod'

// Each turn the adapter serves the next scripted response; every cell below re-scripts it, so
// cells stay deterministic however often you press Run.
const scripted = new MockAdapter({ responses: [] })

const app = adk({ name: 'guardrails', adapters: { openai: scripted } })

// The tool records what it actually did — that is how we prove a guardrail stopped it.
const issued: number[] = []

const refund = app.tool({
  name: 'refund',
  description: 'Refund a payment, in pence',
  schema: z.object({ amount: z.number() }),
  execute: (ctx) => {
    issued.push(ctx.args.amount)
    return { refunded: ctx.args.amount }
  },
})

const support = app.agent({
  name: 'support',
  model: openai('gpt-5.6-luna'),
  context: [app.context.system('Refund what the customer asks for.'), app.context.history()],
  tools: [refund],
})

support.name

Now a hook that only watches. onEvent sees the stream as it happens — the same events that land in run.session.events — while the phase methods bracket the work. In the output, beforeTool fires before the tool runs, and afterTool receives the finished tool_result event, result payload and all.

const seen: string[] = []

scripted.setResponses([
  { toolCalls: [{ name: 'refund', args: { amount: 4000 } }] },
  { text: 'Refunded 4000. Anything else?' },
])

const traced = await app.run(support, {
  input: 'Refund my last order.',
  hooks: [
    {
      name: 'trace',
      onEvent: (event) => {
        seen.push(`event ${event.type}`)
      },
      beforeAgent: (ctx) => {
        seen.push(`beforeAgent ${ctx.runnable.name}`)
      },
      beforeTool: (ctx, call) => {
        seen.push(`beforeTool ${call.name}`)
      },
      afterTool: (ctx, result) => {
        seen.push(`afterTool ${result.name} -> ${JSON.stringify(result.result)}`)
      },
      afterAgent: (ctx, output) => {
        seen.push(`afterAgent ${typeof output}`)
      },
    },
  ],
})

seen

Every method here returned undefined, which is what makes it an observer. The moment one returns a value it becomes an interceptor — section 3. Two warnings the types will not give you:

• beforeAgent returning a string replaces the run's output. Use a braced body when you only meant to log.
• afterTurn fires only under app.handler.turn, plus the rest and agui handlers that delegate to it. Never under a bare app.run.

Step 2

Composition order

Hooks attach at three places: adk({ hooks }) for the app, app.agent({ hooks }) for one agent, and app.run(…, { hooks }) for one call. The runner flattens all three into a single hook — app outermost, then agent, then call site — and the flattening rule is the interesting part. Before hooks run outer to inner and the first non-undefined return wins, so an outer layer can pre-empt an inner one. After hooks run inner to outer, each free to rewrite what the previous returned, so an outer layer gets the last word on the result. Observation is different again: onEvent and onStep fan out to every hook, and their errors are swallowed — watching must never abort a run, while intercepting is control flow and throws.

composeHooks is that flattening, exported so you can build a bundle yourself and pass it anywhere a single hook goes. The built-ins are ordinary hooks too: loggingHook logs agent and tool boundaries, metricsHook turns events into counter callbacks, and consoleHook renders a streaming run to stdout. That last one writes ANSI to process.stdout, so it belongs in a terminal, not this page. Each is also reachable as app.hook.logging(), app.hook.metrics() and app.hook.console().

import { composeHooks, metricsHook } from '@animahealth/adk'
import type { Hook } from '@animahealth/adk'

const unwound: string[] = []
const measured: string[] = []

const stamp = (label: string): Hook => ({
  name: label,
  beforeTool: () => {
    unwound.push(`before ${label}`)
  },
  afterTool: () => {
    unwound.push(`after ${label}`)
  },
})

// One hook out of three: a built-in and two hand-written layers.
const bundle = composeHooks([
  metricsHook({
    onToolResult: (name, durationMs, error) => {
      measured.push(`${name} ${error ? 'failed' : 'ok'}`)
    },
  }),
  stamp('outer'),
  stamp('inner'),
])

scripted.setResponses([
  { toolCalls: [{ name: 'refund', args: { amount: 250 } }] },
  { text: 'Refunded 250.' },
])

await app.run(support, { input: 'Refund the delivery fee.', hooks: [bundle] })

const composition = { unwound, measured }

composition

Read unwound: before goes outer then inner, after comes back inner then outer. That is why a redaction hook belongs outside a logging hook — the logger sees whatever the redactor already rewrote.

Deterministic tool calls

Run a tool without asking the model to choose it

Return a ModelStepResult from beforeModel to bypass that provider call. Include a tool call in both stepEvents and toolCalls, with terminal: false. The runtime records the call and runs it through the normal tool pipeline, including argument validation and tool hooks.

This example chooses a fixed refund in code. The refund tool above only records an amount in an array. On the next iteration, the hook sees the tool result and ends the run.

import type { Hook } from '@animahealth/adk'
import type { ToolCallEvent } from '@animahealth/adk'

issued.length = 0
scripted.reset()

const fixedRefund: Hook = {
	name: 'fixed_refund',
	beforeModel: (ctx, renderCtx) => {
		const refunded = ctx.session.events.some((event) =>
			event.type === 'tool_result' &&
			event.invocationId === ctx.invocationId &&
			event.name === 'refund',
		)
		if (refunded) {
			return { stepEvents: [], toolCalls: [], terminal: true }
		}

		const call: ToolCallEvent = {
			id: crypto.randomUUID(),
			callId: crypto.randomUUID(),
			type: 'tool_call',
			createdAt: Date.now(),
			invocationId: ctx.invocationId,
			agentName: renderCtx.agentName,
			name: 'refund',
			args: { amount: 250 },
		}
		return { stepEvents: [call], toolCalls: [call], terminal: false }
	},
}

const forced = await app.run(support, {
	input: 'Apply the fixed delivery refund.',
	hooks: [fixedRefund],
})

const bypassResult = {
	status: forced.status,
	modelCalls: scripted.stepCalls.length,
	refunds: [...issued],
	toolResults: forced.session.events.filter((event) => event.type === 'tool_result'),
}
bypassResult

The result shows modelCalls: 0 and refunds: [250], with a recorded tool result. The hook chose the call; the tool still executed. To let the model handle other cases or explain a tool result, return undefined instead. The next model call proceeds normally.

This control sits inside an agent's loop. Use a step when the decision belongs between workflow stages. Use a beforeModel hook when you want to replace a particular model decision while keeping the agent's tools and context.

Step 3

A hook that says no

Interception is the return value. beforeTool returning a ToolResultEvent means this is the result: the tool never executes, the event is appended to the session, and the model reads it on the next turn and explains itself. It fires before the arguments are parsed and before the tool is even resolved, so the hook sees what the model asked for — the right place for a cap, an allow-list, or a permission check.

The symmetric returns elsewhere: beforeModel returning a ModelStepResult skips the provider call, afterModel and afterTool returning a value replace the result, and beforeModel/afterModel may also return a Runnable to hand the invocation to a different agent. beforeTool and afterTool cannot transfer — a tool-level handoff has no coherent meaning.

issued.length = 0 // rerunnable: forget what the earlier cells refunded

const refundCap: Hook = {
  name: 'refund_cap',
  beforeTool: (ctx, call) => {
    const amount = Number(call.args.amount)
    if (call.name === 'refund' && amount > 5000) {
      return {
        id: call.id,
        type: 'tool_result',
        createdAt: Date.now(),
        invocationId: call.invocationId,
        agentName: call.agentName,
        callId: call.callId,
        name: call.name,
        error: `Refunds over 5000 need a human. The model asked for ${amount}.`,
      }
    }
  },
}

scripted.setResponses([
  { toolCalls: [{ name: 'refund', args: { amount: 12000 } }] },
  { text: 'That refund is over my limit — a manager has to approve it.' },
])

const capped = await app.run(support, { input: 'Refund my £120 order.', hooks: [refundCap] })

const cappedReport = { executed: issued, text: capped.output.text }

cappedReport

executed is empty: the model asked, the hook answered, your money stayed put. One asymmetry: a vetoed call skips afterTool entirely, because there was no tool result to post-process. Put audit logging in beforeTool or onEvent if it must see the calls that were refused.

Step 4

What a throw actually does

A tool that throws does not fail the run. Every failure becomes an ErrorContext — the invocation, the phase (model, tool, callback or render), the attempt number, the error — and is offered to the error handlers. With no handler registered the default is asymmetric. A tool error is skipped, recorded as the error field of its tool_result so the model can see it and react. A model error is thrown, because there is nothing left to reason with.

import { isToolResultEvent } from '@animahealth/adk'

const lookupOrder = app.tool({
  name: 'lookup_order',
  description: 'Look up an order by id',
  schema: z.object({ id: z.string() }),
  timeout: 50,
  execute: async (ctx) => {
    if (ctx.args.id === 'A-42') throw new Error('order service unreachable')
    await new Promise((resolve) => setTimeout(resolve, 2000)) // slower than the 50ms timeout
    return { id: ctx.args.id, status: 'shipped' }
  },
})

const orderDesk = app.agent({
  name: 'order_desk',
  model: openai('gpt-5.6-luna'),
  context: [app.context.system('Look the order up before answering.'), app.context.history()],
  tools: [lookupOrder],
})

scripted.setResponses([
  { toolCalls: [{ name: 'lookup_order', args: { id: 'A-42' } }] },
  { text: 'The order service is down, so I could not check A-42.' },
])

const survived = await app.run(orderDesk, 'Where is order A-42?')

const survivedReport = {
  status: survived.status,
  toolResults: survived.session.events
    .filter(isToolResultEvent)
    .map((event) => ({ name: event.name, error: event.error })),
  text: survived.output.text,
}

survivedReport

The run is completed, not error. That is the shape you want for a flaky dependency and the shape you must override for a dependency whose failure is not survivable — the subject of section 5.

Step 5

Six recovery actions

An error handler is { canHandle?, handle }, and handle returns one of six verdicts:

• throw aborts the run with the original error.
• skip records the error and carries on.
• abort ends the invocation cleanly.
• retry, with an optional delay, runs the same step again.
• fallback substitutes a result as if the step had succeeded.
• pass declines, handing the decision to the next handler.

Handlers are consulted in order — runner, then agent, then call site. The first verdict that is not pass wins. If every handler passes, the phase default from section 4 applies.

Five handlers ship:

• retryHandler — bounded exponential backoff, then pass.
• rateLimitHandler — a retry handler that only fires on rate limit, 429, or too-many-requests messages.
• timeoutHandler — matches timed out, then fallback if you gave it a fallbackResult, otherwise skip.
• loggingHandler — logs and always passes.
• defaultHandler — the phase default, made explicit.

The cell below stacks three of them against a run that fails twice, in two different phases.

import { loggingHandler, retryHandler, timeoutHandler } from '@animahealth/adk'

const failures: string[] = []

scripted.setResponses([
  { error: new Error('503 upstream unavailable') }, // model call fails
  { toolCalls: [{ name: 'lookup_order', args: { id: 'B-7' } }] }, // retry: this one calls the slow tool
  { text: 'B-7 is unconfirmed — the live lookup timed out, so this is the cached status.' },
])

const recovered = await app.run(orderDesk, {
  input: 'Where is order B-7?',
  errorHandlers: [
    // Observes every failure and defers — `pass` keeps the chain moving.
    loggingHandler({
      onError: (ctx) => {
        failures.push(`${ctx.phase} · attempt ${ctx.attempt} · ${ctx.error.message}`)
      },
    }),
    // Ordered before the retry handler: a timeout should degrade, not hammer the dependency.
    timeoutHandler({ fallbackResult: { status: 'unknown', source: 'cache' } }),
    // `retryable` narrows this one to model failures; without it, it would retry everything.
    retryHandler({ maxAttempts: 3, baseDelay: 0, retryable: (ctx) => ctx.phase === 'model' }),
  ],
})

const recoveredReport = {
  failures,
  toolResults: recovered.session.events
    .filter(isToolResultEvent)
    .map((event) => ({ name: event.name, result: event.result })),
  text: recovered.output.text,
}

recoveredReport

Two failures, two different verdicts, one completed run. The model's 503 was retried and the second attempt called the tool; the tool's timeout was substituted with a cached-looking result that the model then wrote its answer from. The ordering is the design here: had retryHandler come first without its retryable predicate, it would have claimed the timeout too and retried a dependency that was already too slow.

Step 6

Timeouts and caps

Deadlines exist at three scopes, and they do different things. A tool's own timeout (milliseconds) races that one execution and raises Tool 'name' timed out after Nms — an ordinary tool-phase error, which is why timeoutHandler can catch it and why the tool_result is flagged timedOut. A tool's retry takes a RetryConfig — spelled out on the tools page — and retries inside the tool, before any error handler is consulted. And app.run(…, { timeout }) bounds the whole run: it races the event stream and rejects with Timeout after Nms, so it is a hard stop, not a recoverable phase error.

Two caps stop a loop that never settles. An agent's maxSteps (default 25) bounds reasoning iterations in one invocation and ends the run with status max_steps rather than an error; maxTurns (default 100) bounds yield-and-resume cycles the same way. A third cap is not configurable: an error handler that keeps answering retry for the same tool call is cut off after ten attempts, so a handler bug degrades into a recorded failure instead of an infinite loop.

Every guardrail decision ends as an event in the session, so it is already in the audit trail you would read anyway.

Which raises the question of where that session lives once the process ends. Next: stores and the sleeping agent.

Step 1

The contract a store implements

SessionStore is seven methods and no cleverness. It persists two things: a session's metadata row plus its events, and scoped state — the values shared by every session bound to one user, patient, practice, org, or team. Everything else the ADK does with sessions (binding scopes, buffering events, tracking what is dirty) sits above the store, in the session service, so a store never has to think about it.

interface SessionStore {
  load(
    appName: string,
    sessionId: string,
  ): Promise<{ session: StoredSession; events: Event[] } | null>

  commit(
    session: StoredSession,
    newEvents: Event[],
    expectedVersion: number,
    scopedChanges?: ScopedStateChange[],
  ): Promise<CommitResult>

  delete(appName: string, sessionId: string): Promise<void>

  loadScopedState(appName: string, scope: string, scopeId: string): Promise<Record<string, unknown>>

  saveScopedState(
    appName: string,
    scope: string,
    scopeId: string,
    state: Record<string, unknown>,
  ): Promise<void>

  close(): Promise<void>

  list(appName: string): Promise<Array<{ id: string; updatedAt: number }>>
}

StoredSession does not carry the events. It is id, appName, version, scopes, and createdAt. Sessions routinely reach several megabytes of event data, so a store that kept events inside the metadata row would rewrite the entire history on every turn — and would hit DynamoDB's 400KB item limit as a hard ceiling on conversation length.

inMemoryStore() is exported from the package root, so the contract is exercisable right here. Commit takes an expectedVersion; 0 means create this session. Commits are append-only and idempotent by event id, so the second commit below — a retried batch that overlaps the stored history — cannot double an event, and its new one still lands at the end in order.

import { inMemoryStore } from '@animahealth/adk'

const store = inMemoryStore()

// The metadata row — no events in it, by design.
const meta = {
  id: 'session_demo',
  appName: 'bookings',
  version: 0,
  scopes: {},
  createdAt: Date.now(),
}

const makeEvent = (n: number) => ({
  id: `evt-${n}`,
  type: 'user' as const,
  createdAt: Date.now() + n,
  text: `message ${n}`,
})

const created = await store.commit(meta, [makeEvent(1), makeEvent(2)], 0)

// The same batch again, one event further on: event 2 is already stored, event 3 is not.
const appended = await store.commit({ ...meta, version: 1 }, [makeEvent(2), makeEvent(3)], 1)

const reread = await store.load('bookings', 'session_demo')

const ledger = {
  created,
  appended,
  events: reread?.events.map((e) => e.id),
  version: reread?.session.version,
}

ledger

Concurrency is optimistic, not locked. Two runtimes can hold the same session; the second one to commit finds the version moved and is told so, with the version it needs. Nothing is written on a rejected commit — not the events, not the scoped-state changes that rode along with it.

// A writer that loaded at version 1, while someone else has already moved the row to 2.
const stale = await store.commit({ ...meta, version: 1 }, [makeEvent(4)], 1)

const afterStale = await store.load('bookings', 'session_demo')

const conflict = {
  stale,
  eventsAfterTheRejectedCommit: afterStale?.events.length,
}

conflict

Why optimistic concurrency rather than a lock or a per-session queue: an agent turn runs for five to sixty seconds. That is far too long to hold a distributed lease — a crashed runtime would strand it — and a per-session queue would park every incoming message behind whatever slow run is in flight.

Scoped state is the store's other surface, and its save is a merge: keys you do not mention are untouched, and a key set to undefined is deleted.

await store.saveScopedState('bookings', 'user', 'u-1', { theme: 'dark', locale: 'en-GB' })
await store.saveScopedState('bookings', 'user', 'u-1', { theme: 'light', locale: undefined })

const scoped = await store.loadScopedState('bookings', 'user', 'u-1')

scoped

Step 2

The row is real only after a commit

Below is a real app on a real store, with the model scripted so the page needs no key (see Testing agents without a model). Everything under the model — session, ledger, store — is the shipped runtime. app.sessions.create() writes the metadata row immediately: version 1, zero events.

import { adk } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'
import { MockAdapter } from '@animahealth/adk/testing'

const app = adk({
  name: 'bookings',
  store: inMemoryStore(),
  adapters: { openai: new MockAdapter({ responses: [{ text: 'Tuesday 14:30 is open.' }] }) },
})

const concierge = app.agent({
  name: 'concierge',
  model: openai('gpt-5.6-luna'),
  context: [app.context.system('Be brief.'), app.context.history()],
  tools: [],
})

const session = await app.sessions.create()

const run = await app.run(concierge, { session, input: { message: 'Anything on Tuesday?' } })

// Read the row back from the store while the run's events are still only in memory.
const onDisk = await app.sessions.get(session.id)

const afterRun = {
  runStatus: run.status,
  said: run.output.text,
  eventsInMemory: session.events.length,
  eventsInTheStore: onDisk?.events.length,
}

afterRun

The run completed, the agent replied, and the store holds nothing. Now commit. The version advances, the whole ledger lands, and the reloaded row answers for the agent — the reply comes back out of storage, not out of the object you still have in scope.

const committed = await app.sessions.commit(session)

const reloaded = await app.sessions.get(session.id)

const afterCommit = {
  committed,
  eventsInTheStore: reloaded?.events.length,
  versionInTheStore: reloaded?.version,
  saidByTheReloadedRow: reloaded?.output.text,
  ledger: reloaded?.events.map((e) => e.type),
}

afterCommit

Pass no session at all and app.run builds one for the duration of the call. It is never registered with the store, so it is absent from app.sessions.list() — the listing that a "pending work" screen or a sweeper reads. It is not lost, though: nothing wrote it, and committing it afterwards creates the row.

const orphan = await app.run(concierge, 'Anything on Wednesday?')

const listedBefore = await app.sessions.list()
const rescued = await app.sessions.commit(orphan.session)
const listedAfter = await app.sessions.list()

const listing = {
  orphanId: orphan.session.id,
  listedBefore: listedBefore.map((s) => s.id),
  rescued,
  listedAfter: listedAfter.map((s) => s.id),
}

listing

When the handlers commit for you they resolve conflicts too, and report which way it went in commitStatus; the four words it can hold are tabled in serving. When you are done with the app, app.close() closes the store, so a CLI or a worker exits instead of hanging on a live pool.

Step 3

The four stores

Which store is a deployment decision, not an agent one. The agent, the tools, and the session code are identical across all four; only the line that builds the app changes. The three backed stores sit behind subpath exports, with their drivers as optional peers.

In-memory

The default. adk() with no store is already using it. Maps in the process; everything is gone when the process exits. It holds the same append-by-id dedup and the same OCC semantics as the SQL stores, which is what makes it a legitimate stand-in for them in tests.

import { adk, inMemoryStore } from '@animahealth/adk'

const app = adk({ name: 'bookings', store: inMemoryStore() })
// identical to: adk({ name: 'bookings' })

SQLite

Zero infrastructure and durable — a file. This is the right store for local development, for a CLI, and for a single-process deployment. Parent directories are created for you, and the connection runs in WAL mode. Pass ':memory:' for an ephemeral database that still exercises the real SQL path.

import { adk } from '@animahealth/adk'
import { sqliteStore } from '@animahealth/adk/stores/sqlite'

const app = adk({ name: 'bookings', store: sqliteStore('./data/bookings.db') })

// npm install better-sqlite3   (optional peer, >=11)

A commit — the version bump, the event appends, and the scoped-state writes — is one transaction, so a rejected commit writes nothing at all.

Postgres

The multi-process store: several web nodes and workers sharing one session table, with OCC as the referee between them. Either hand it a connection string and let it build a pool, or hand it a pool you already manage — the store leaves an injected pool entirely alone, including its error handling and shutdown. It throws at construction if given neither.

import { adk } from '@animahealth/adk'
import { postgresStore } from '@animahealth/adk/stores/postgres'

const app = adk({
  name: 'bookings',
  store: postgresStore({ connectionString: process.env.DATABASE_URL }),
})

// or bring your own pool — the store will not close or re-configure it:
import { Pool } from 'pg'

const shared = new Pool({ connectionString: process.env.DATABASE_URL, max: 20 })
const store = postgresStore({ pool: shared })

// npm install pg   (optional peer, >=8)

Every commit runs inside BEGIN/COMMIT on one dedicated client from the pool, so a version conflict rolls the whole thing back — there is no window in which the version advanced but the events did not.

DynamoDB

Single-table, serverless, and the only store with no transaction across items. The table needs a string partition key and a string sort key; their names default to pk and sk and are configurable if your table already uses others.

import { adk } from '@animahealth/adk'
import { dynamoStore } from '@animahealth/adk/stores/dynamodb'

const app = adk({
  name: 'bookings',
  store: dynamoStore({
    tableName: 'adk-sessions',
    client: { region: 'eu-west-2' }, // any DynamoDBClientConfig
    partitionKey: 'pk', // default
    sortKey: 'sk', // default
  }),
})

// npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb   (optional peers, >=3)

Two caveats, both in the source. First, atomicity: the metadata PutItem is the OCC gate and runs first; events and scoped state follow as batched writes. If the gate succeeds and a batch then fails, the version has advanced without its events. Second, list() is a table Scan — the key layout has no app-level partition — so put a GSI over a dedicated app-name attribute in front of it before leaning on it at scale.

Step 4

What lands on disk, and who creates it

Three tables, the same shape in SQLite and Postgres: the session row, the event log keyed by event id and ordered by idx, and scoped state. Nothing else of a sleeping agent lands on disk.

-- Postgres. SQLite is the same three tables with TEXT/INTEGER in place of JSONB/BIGINT.
CREATE TABLE IF NOT EXISTS sessions (
  app_name TEXT NOT NULL,
  id TEXT NOT NULL,
  version INTEGER NOT NULL DEFAULT 0,
  scopes JSONB NOT NULL DEFAULT '{}',
  created_at BIGINT NOT NULL,
  updated_at BIGINT NOT NULL,
  PRIMARY KEY (app_name, id)
);

CREATE TABLE IF NOT EXISTS events (
  app_name TEXT NOT NULL,
  session_id TEXT NOT NULL,
  event_id TEXT NOT NULL,
  idx INTEGER NOT NULL,
  data JSONB NOT NULL,
  PRIMARY KEY (app_name, session_id, event_id)
);

CREATE INDEX IF NOT EXISTS idx_events_order
  ON events (app_name, session_id, idx);

CREATE TABLE IF NOT EXISTS scoped_state (
  app_name TEXT NOT NULL,
  scope TEXT NOT NULL,
  scope_id TEXT NOT NULL,
  key TEXT NOT NULL,
  value JSONB NOT NULL,
  PRIMARY KEY (app_name, scope, scope_id, key)
);

There is no migration step to run. Both SQL stores issue that DDL themselves — SQLite when it opens the file, Postgres once per store instance before its first query. It is IF NOT EXISTS throughout, so it is safe to run from every process on every boot. The practical consequence is a permissions one: the role your Postgres store connects as needs table-creation rights the first time it runs against a fresh database. A SELECT/INSERT-only role will fail on that first statement, not on the first commit.

The tables are unqualified, so they land in the connection's current schema — point the store at a dedicated database or set the search_path if you want them somewhere specific.

DynamoDB has no DDL to issue, so its one piece of provisioning is yours: create the table with a string HASH key and a string RANGE key. Everything the store writes — the meta item, one item per event, one item per scoped-state key — is keyed inside that pair.

// The table this store expects. Events sort by (v, seq): `v` is the session version the OCC gate
// just granted, `seq` the 0-based position within that commit's batch — both known at write time,
// with no read-before-write and no counter to race on.
await client.send(
  new CreateTableCommand({
    TableName: 'adk-sessions',
    AttributeDefinitions: [
      { AttributeName: 'pk', AttributeType: 'S' },
      { AttributeName: 'sk', AttributeType: 'S' },
    ],
    KeySchema: [
      { AttributeName: 'pk', KeyType: 'HASH' },
      { AttributeName: 'sk', KeyType: 'RANGE' },
    ],
    BillingMode: 'PAY_PER_REQUEST',
  }),
)

Step 5

One suite, four stores

The suite is the contract for a store you write yourself: implement the seven methods, register it with runSessionStoreTests(name, createStore, cleanup), and any gap between your store and the shipped ones surfaces as a failure in the same assertions. It is what backs "they implement the same interface" for the shipped stores too, and SQLite registers twice — as a file and as ':memory:'.

// Every store registers against the same suite.
runSessionStoreTests('InMemoryStore', () => new InMemoryStore())
runSessionStoreTests('SQLiteStore', /* a throwaway file database */)
runSessionStoreTests('SQLiteStore (:memory:)', /* the advertised ephemeral mode */)
runSessionStoreTests('PostgresStore', /* against a live Postgres */)
runSessionStoreTests('DynamoDBStore', /* against a live DynamoDB endpoint */)

The suite covers load, commit, delete, list, and scoped state — including the behaviours that are easy to get subtly wrong and impossible to notice: event order preserved within a batch and across batches, a re-committed event id neither duplicated nor allowed to disturb later ordering, scoped state written atomically with the commit and not written on a conflict, a conflict returned for a commit against a deleted session, and batches larger than DynamoDB's 25-item write limit. The second SQLite registration is not redundant: ':memory:' has its own failure shape, where a second connection is a second, empty database.

The in-memory and SQLite registrations run anywhere. The Postgres and DynamoDB ones need a live endpoint to point at; without one they report themselves skipped rather than passing.

Step 6

A sleeping agent you can run

The Bookings sample in the package is this chapter with a filesystem attached: the session becomes a row in bookings.db, the process exits, and a later command resumes the run from where it paused. The store is one line of the app, and every command that runs the agent also commits it.

// sample/src/bookings.ts
export const app = adk({
  name: 'bookings',
  schema: { session: { confirmation: confirmation.optional() } },
  store: sqliteStore(DB_PATH),
})

// sample/src/cli.ts
const session = await app.sessions.create()
const result = await app.run(bookingAgent, { session })
await app.sessions.commit(session)

Step 1

One request, one turn

app.handler carries turn, rest, agui and voice. The first three are one thing wearing three coats: turn is the atom — session in, one run, commit, result out — and it returns a stream. rest drains that stream and returns a JSON body; agui translates it into the AG-UI protocol. Both call turn.

Each takes a config once and hands back a function you call per request. The config is the deployment's business — which agent, which store, which hooks, how much to report. The per-request part is two fields: a sessionId and an input.

interface HandlerInput {
  sessionId?: string
  input: Input // { message?, tools?, state?, initialState? }
}

// app.handler.* fills in the app's name, schema and store, and prepends the app's own
// hooks and error handlers to these.
interface HandlerConfig {
  agent: Runnable
  schema?: StateSchema
  sessionService?: SessionService
  hooks?: Hook[]
  errorHandlers?: ErrorHandler[]
  timeout?: number
  response?: { events?: boolean; usage?: boolean; state?: boolean }
}

Omit the sessionId and the handler mints one. Supply it and the handler loads that row, or starts it if there is nothing there yet. Ids are normalised on the way in, so thread-42 and session_thread-42 are the same thread.

Here is the agent the rest of the page serves. The model is stood down by a hook — beforeAgent returning a string replaces the run's output before any model is reached (see Guardrails and recovery). Everything under it is the shipped request path.

import { adk } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'
import { z } from 'zod'

const app = adk({ name: 'bookings' })

const lookupStay = app.tool({
  name: 'lookup_stay',
  description: 'Look up a booking by its reference',
  schema: z.object({ ref: z.string() }),
  execute: (ctx) => ({ ref: ctx.args.ref, nights: 3 }),
})

const concierge = app.agent({
  name: 'concierge',
  model: openai('gpt-5.6-luna'),
  context: [app.context.system('Answer booking questions.'), app.context.history()],
  tools: [lookupStay],
})

// The model, stood down: this hook answers before the model call, so every handler on this page
// runs with no key. Delete it and the same code talks to OpenAI.
const scripted = (text: string) => [{ beforeAgent: () => text }]

concierge.name

Step 2

The REST handler

app.handler.rest(config) returns (input) => Promise<RestResponse>. It runs the turn to completion and hands back a plain object you can serialise. That is the whole surface: no framework, no router, no middleware contract.

const askConcierge = app.handler.rest({
  agent: concierge,
  hooks: scripted('Three nights, checking out Friday.'),
  response: { state: true },
})

const reply = await askConcierge({
  sessionId: 'thread-42',
  input: { message: 'How long is my stay?', state: { channel: 'sms' } },
})

reply

Three fields are always there — sessionId, status, output — and the rest depend on the turn. yieldedTools appears when it yielded, error when it failed, warning when the commit was messy. The other three are opt-in, because a chat client and an audit endpoint want different amounts of the turn:

One caveat on the last of those: events is typed Event[], but a stream also carries assistant_delta and thought_delta, which are not ledger events. Narrow on type before you trust an entry, or read the ledger from the session instead.

Call the same handler again on the same sessionId and the second turn resumes a conversation nobody kept in memory, because the first one committed before it returned.

const secondReply = await askConcierge({
  sessionId: 'thread-42',
  input: { message: 'And the checkout time?' },
})

const thread = await app.sessions.get('thread-42')

const durable = {
  turns: [reply.status, secondReply.status],
  eventsOnDisk: thread?.events.length,
  version: thread?.version,
  ledger: thread?.events.map((event) => event.type),
}

durable

handler.rest and handler.turn commit after every turn, so serving an agent needs no persistence code of your own — which store the rows land in, and what a bare app.run does instead, are Where a sleeping agent lives.

Behind an HTTP server it stays this small. The handler is built once, at boot; the request body supplies the two fields.

import { createServer } from 'node:http'

import { adk } from '@animahealth/adk'
import { postgresStore } from '@animahealth/adk/stores/postgres'

const bookings = adk({
  name: 'bookings',
  store: postgresStore({ connectionString: process.env.DATABASE_URL }),
})

const ask = bookings.handler.rest({ agent: concierge, response: { usage: true } })

createServer(async (req, res) => {
  const chunks: Buffer[] = []
  for await (const chunk of req) chunks.push(chunk as Buffer)
  const body = JSON.parse(Buffer.concat(chunks).toString())

  const turn = await ask({ sessionId: body.sessionId, input: { message: body.message } })

  res.writeHead(turn.status === 'error' ? 500 : 200, { 'content-type': 'application/json' })
  res.end(JSON.stringify(turn))
}).listen(3000)

Step 3

A turn that stops

A yielding tool crossing a request boundary needs no extra protocol. The turn comes back yielded_tool with the calls it is waiting on; a later request carries the answers in input.tools. That is the pause-and-resume of Stopping to ask, with HTTP in the gap instead of a runTest step.

// POST /turns { "sessionId": "y1", "message": "book me in" }
const paused = await ask({ sessionId: 'y1', input: { message: 'book me in' } })

// paused.status       → 'yielded_tool'
// paused.output.items → []                       (nothing was said; the turn stopped)
// paused.yieldedTools → [{ callId: 'call_125f…', name: 'ask_guest', args: { q: 'Which night?' } }]

// POST /turns { "sessionId": "y1", "tools": [{ "callId": "call_125f…", "input": { … } }] }
if (paused.status === 'yielded_tool' && paused.yieldedTools) {
  const [pending] = paused.yieldedTools

  const resumed = await ask({
    sessionId: paused.sessionId,
    input: { tools: [{ callId: pending.callId, input: { answer: 'Friday' } }] },
  })

  // resumed.status      → 'completed'
  // resumed.output.text → 'Booked for Friday.'
}

Hence the guard. RunResult is a discriminated union, so status === 'yielded_tool' is enough there. RestResponse is a flat object with optional fields, so check yieldedTools yourself.

Between those two requests the agent is rows. Nothing is held open, so the process that asked the question and the process that receives the answer need not be the same one.

Step 4

The stream underneath

app.handler.turn(config) returns (input) => StreamResult<TurnResult> — an async iterable of stream events that returns the turn result. Take it when you want the tokens as they arrive: a server-sent-event endpoint, a websocket, a CLI.

The stream is lazy: it starts when something awaits or iterates it, not when you call the handler. And the TurnResult is the generator's return value, which a for await loop throws away, so drive the iterator by hand when you need it.

const streamTurn = app.handler.turn({
  agent: concierge,
  hooks: scripted('Checkout is at eleven.'),
})

const live = streamTurn({ sessionId: 'thread-42', input: { message: 'Remind me again?' } })

const streamedTypes: string[] = []
const iterator = live[Symbol.asyncIterator]()
let step = await iterator.next()
while (!step.done) {
  streamedTypes.push(step.value.type)
  step = await iterator.next()
}

const outcome = {
  invocationId: live.invocationId,
  streamed: streamedTypes,
  status: step.value.status,
  commitStatus: step.value.commitStatus,
  sessionId: step.value.sessionId,
}

outcome

Sparse, because the model on this page never runs: a real turn also streams model_start, assistant_delta, tool_call, model_end. What matters is the pair around them — invocation_start opens the turn, and after invocation_end the result carries a commitStatus the stream never mentioned. That word is the next section.

live.abort() stops the run. An aborted turn does not commit at all: its commitStatus is undefined and its events stay where they were. So does a turn that threw — the result comes back status: 'error' with the message, and nothing is written.

Step 5

The AG-UI handler

AG-UI is a protocol for agent front-ends: a fixed vocabulary of events a generic client can render without knowing what framework produced them. app.handler.agui(config) returns (input) => AsyncIterable<AGUIEvent>, ready to write down an SSE connection.

import { createServer } from 'node:http'

const ui = bookings.handler.agui({ agent: concierge })

createServer(async (req, res) => {
  const url = new URL(req.url ?? '/', 'http://localhost')
  res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' })

  for await (const event of ui({
    sessionId: url.searchParams.get('session') ?? undefined,
    input: { message: url.searchParams.get('message') ?? '' },
  })) {
    res.write(`data: ${JSON.stringify(event)}\n\n`)
  }

  res.end()
}).listen(3001)

Any writer that can frame SSE will do. Behind AWS Lambda the same iterable goes to a streamed response, which is examples/lambda-agui.ts.

Every stream is bracketed the same way. RUN_STARTED carries the session as threadId and the invocation as runId. Then a STATE_SNAPSHOT, which is always empty. State never crosses this edge, because state_change events carry every scope, patient and practice included. Then the turn's events, translated one by one:

A text message therefore exists only if the model streamed deltas. The end of the run says which way it went: RUN_FINISHED carrying result: { commitStatus } when the turn finished — that result field is where a client reads whether the turn was written — a CUSTOM named RUN_INTERRUPTED when it yielded (the pending callId and tool name ride in its value), and RUN_ERROR — with no RUN_FINISHED — when it failed or was aborted.

handler.agui is a thin loop over handler.turn, and the translator it uses is exported. AgUIAdapter takes options the handler does not forward — step events, reasoning off, raw events attached, a transformer per yielding tool — so when you want those, or a protocol that is not AG-UI at all, write the loop yourself.

import { AgUIAdapter } from '@animahealth/adk/agui'

const runTurn = bookings.handler.turn({ agent: concierge })

async function* protocol(sessionId: string, message: string) {
  const live = runTurn({ sessionId, input: { message } })
  const adapter = new AgUIAdapter(sessionId, live.invocationId, { includeSteps: true })

  yield adapter.runStarted()

  const iterator = live[Symbol.asyncIterator]()
  let step = await iterator.next()
  while (!step.done) {
    yield* adapter.transform(step.value)
    step = await iterator.next()
  }

  yield adapter.runFinished({ commitStatus: step.value.commitStatus })
}

Step 6

Four ways a turn ends up on disk

Sessions are guarded by a version, not a lock — that is the store's bargain, argued in Where a sleeping agent lives — so a handler must decide what to do when a commit is refused, and commitStatus on the turn result reports which way it decided:

Underneath are the two calls the handler makes for you, and you can make them yourself. Load one session twice — two requests, two processes, same row — and watch the second commit be refused.

await app.sessions.create({ sessionId: 'thread-shared' })

const replicaOne = await app.sessions.get('thread-shared')
const replicaTwo = await app.sessions.get('thread-shared')
if (!replicaOne || !replicaTwo) throw new Error('no session thread-shared')

const loadedAt = [replicaOne.version, replicaTwo.version]

replicaOne.input.message('from the first request')
replicaTwo.input.message('from the second request')

const won = await app.sessions.commit(replicaOne)
const lost = await app.sessions.commit(replicaTwo)
const rescued = await app.sessions.merge(replicaTwo)
const settled = await app.sessions.get('thread-shared')

const conflict = {
  loadedAt,
  won,
  lost,
  rescued,
  version: settled?.version,
  ledger: settled?.events.map((event) => (event.type === 'user' ? event.text : event.type)),
}

conflict

The refusal is data, not an exception: { ok: false, conflict: true, currentVersion }, and it tells you the version you needed. Nothing was written — not the events, not the scoped state riding with them. merge then re-reads the head and appends this writer's new events onto it, so both messages survive. Losing a race costs an extra round trip, not a turn.

Step 7

Two turns, one session

Now the same collision through the handlers, with no conflict simulated. Two turns are started against one sessionId. In the first pair a slow turn is overtaken by a message that arrives while it is still thinking. In the second, both arrive at once.

const slowConcierge = app.handler.turn({
  agent: concierge,
  hooks: [
    {
      beforeAgent: async () => {
        await new Promise((resolve) => setTimeout(resolve, 150))
        return 'the slow answer'
      },
    },
  ],
})
const fastConcierge = app.handler.turn({ agent: concierge, hooks: scripted('the fast answer') })

// Promise.resolve starts a lazy turn stream, so the second request lands mid-flight.
const slowTurn = Promise.resolve(
  slowConcierge({ sessionId: 'race', input: { message: 'first question' } }),
)
await new Promise((resolve) => setTimeout(resolve, 30))
const fastTurn = Promise.resolve(
  fastConcierge({ sessionId: 'race', input: { message: 'second question' } }),
)

const [slowOutcome, fastOutcome] = await Promise.all([slowTurn, fastTurn])
const raced = await app.sessions.get('race')

const together = app.handler.turn({ agent: concierge, hooks: scripted('either answer') })
const [firstOutcome, secondOutcome] = await Promise.all([
  Promise.resolve(together({ sessionId: 'tie', input: { message: 'A' } })),
  Promise.resolve(together({ sessionId: 'tie', input: { message: 'B' } })),
])
const tied = await app.sessions.get('tie')

const said = (session: typeof raced) =>
  session?.events.map((event) => (event.type === 'user' ? event.text : event.type))

const race = {
  overtaken: {
    slow: [slowOutcome.status, slowOutcome.commitStatus],
    fast: [fastOutcome.status, fastOutcome.commitStatus],
    ledger: said(raced),
  },
  together: {
    first: [firstOutcome.status, firstOutcome.commitStatus],
    second: [secondOutcome.status, secondOutcome.commitStatus],
    ledger: said(tied),
  },
}

race

Read the first ledger. The slow turn ran to completed and produced an answer, and none of it is there — not the reply, not even the question that started it. The rule is a timestamp comparison: on a rejected commit the handler re-reads the row, and if it holds a user message newer than this turn's own, the whole uncommitted slice is dropped. The guest moved on, so the answer to the old question would arrive out of order.

The second ledger is the other outcome: nothing overtook anything, so the loser merged and both exchanges are on the row, in commit order. One question separates the two — did a newer user message land while this turn was running.

Step 1

What changes

app.handler carries turn, rest, agui and voice. The first three are the request shape of Serving it: a config in, a function you call per request out. voice is the odd one. There is no request. A call arrives at a LiveKit room, and what the handler hands back is a worker.

Here is a whole voice program: one tool, one agent, one handler, and two closing lines unlike anything else in the package.

import { fileURLToPath } from 'node:url'

import { z } from 'zod'

import { adk } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'

const app = adk({ name: 'bookings' })

const lookupStay = app.tool({
  name: 'lookup_stay',
  description: 'Look up a booking by its reference',
  schema: z.object({ ref: z.string() }),
  execute: (ctx) => ({ ref: ctx.args.ref, nights: 3 }),
})

const concierge = app.agent({
  name: 'concierge',
  model: openai.realtime('gpt-realtime-1.5', { voice: 'ballad' }),
  context: [app.context.system('Answer booking questions.'), app.context.history()],
  tools: [lookupStay],
  timeouts: { inactivity: 15_000, expiry: 300_000 },
})

const handler = app.handler.voice({ agent: concierge })

export default handler
handler.start(fileURLToPath(import.meta.url))

That file is both the worker and the thing that launches it. start(entryFile) boots a LiveKit agent server and tells it which module to load per job. LiveKit spawns a subprocess per call and reads that module's default export, which must carry an entry function and either a prewarm function or none. The handle is that shape, so export default handler is the whole wiring. Inside a spawned subprocess start returns immediately instead of booting a second server. That is why one file can be both.

Run it the way LiveKit runs a worker — the subcommand is read from process.argv:

npx tsx call.ts dev      # reload on change, for local iteration
npx tsx call.ts start    # production
npx tsx call.ts connect  # join one named room and exit

Two things are checked at construction, before you deploy. app.handler.voice requires @livekit/agents to be installed and throws when it is not — the core package never imports it, and the import happens the moment you call voice(). And the runnable must be an agent carrying a realtime model config; a sequence, a step, or an agent on an ordinary chat model is rejected with a message naming openai.realtime() and gemini.realtime().

Step 2

What has to be running

The ADK does not carry the media stack. LiveKit does: a room server that the caller and your worker both connect to, and — for a real phone number — a SIP trunk in front of it. Self-host it or use LiveKit Cloud; either way the worker finds it through three environment variables, read by the LiveKit CLI at boot.

LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=…
LIVEKIT_API_SECRET=…
OPENAI_API_KEY=…            # or GOOGLE_API_KEY for a Gemini realtime model

The peers are opt-in, and each one buys a specific feature. Install the first two (or the Google plugin instead) and you have a working call; the rest are for what you add later.

npm install @livekit/agents @livekit/agents-plugin-openai

The last two rows arrive on their own: @livekit/agents depends on livekit-server-sdk and declares @livekit/rtc-node as its own peer. They are listed because the ADK loads them lazily, by name. A broken install therefore shows up as a missing feature, not a missing module: egress recording that logs and returns, local capture that warns and skips.

Step 3

The realtime model

A realtime config is a wrapper, not a model. RealtimeModelConfig holds realtime: true and the inner provider model. Around it go the audio-side settings the inner model has no vocabulary for: which voice, how turns are detected, how speech is transcribed, how input noise is handled. Three shapes come out of that wrapper, and whether you pass stt and tts decides which one you get.

import { gemini } from '@animahealth/adk/gemini'
import { openai } from '@animahealth/adk/openai'
import { realtime } from '@animahealth/adk/voice'

// Speech in, speech out, one model.
const speechToSpeech = openai.realtime('gpt-realtime-1.5', {
  voice: 'ballad',
  turnDetection: { type: 'semantic', silenceDurationMs: 500 },
  inputTranscription: { model: 'gpt-4o-mini-transcribe' },
  noiseReduction: { type: 'near_field' },
})

const geminiLive = gemini.realtime('gemini-live-2.5-flash-native-audio', { voice: 'Puck' })

// Half-cascade: the realtime model reasons in text, your TTS speaks.
const halfCascade = openai.realtime('gpt-realtime-1.5', { tts: elevenLabsTTS })

// Full pipeline: an ordinary chat model between an STT and a TTS.
const pipeline = realtime({ model: openai('gpt-5.6-luna'), stt: deepgramSTT, tts: elevenLabsTTS })

stt and tts are LiveKit plugin instances, typed unknown by the ADK so the core carries no dependency on them. Anything else the provider accepts goes through providerOptions, which is merged last and therefore wins over everything the ADK computed.

Voice mode speaks to two providers. A realtime config on any other provider is rejected when the call starts, with the provider named. Gemini's Vertex settings ride on the inner model — gemini.realtime(name, { vertex: { project, location } }) — and are translated into the plugin's own Vertex options.

Voice resolves its OpenAI connection separately from text mode and understands one environment override: OPENAI_EU_API_KEY routes the realtime connection at the EU endpoint. Otherwise it passes nothing and the LiveKit plugin reads OPENAI_API_KEY itself. Azure endpoints configured for text mode are not carried into a call.

Step 4

Which session the call joins

A request carries its own sessionId. A call carries a room and a participant, so the handler asks you. setup runs once, after the worker has connected to the room and the caller has joined, and its return value decides which session row this call appends to. Omit it and the room's name is the session id.

const app = adk({
  name: 'bookings',
  schema: {
    session: { caller: z.string().default('unknown'), channel: z.string().default('voice') },
  },
})

const handler = app.handler.voice({
  agent: concierge,
  name: 'concierge-voice',
  setup: (participant) => ({
    sessionId: participant.attributes?.['booking_ref'] ?? `call-${Date.now()}`,
    state: { caller: participant.identity ?? 'unknown', channel: 'voice' },
  }),
  sound: { noiseCancellation: 'telephony' },
  timeouts: { inactivity: 15_000, expiry: 600_000 },
})

participant is thin by design — identity and attributes, the two fields a SIP trunk or a token can populate. That is enough to route a caller back to the thread they were on last week. Return that thread's id and the agent picks up a history nobody had to hand it — the ledger was already there.

The rest of the config is the deployment's business, once, at boot:

interface VoiceHandlerConfig {
  agent: Runnable                       // must be an agent on a realtime model
  schema?: StateSchema
  setup?: (participant: VoiceParticipant) => SessionSetup | Promise<SessionSetup>
  sound?: SoundConfig                   // noise cancellation, thinking sound
  recording?: RecordingConfig           // { dir?, egress? }
  callTermination?: false | CallTerminationConfig
  hooks?: VoiceHook[]
  errorHandlers?: ErrorHandler[]
  timeouts?: AgentTimeouts              // { inactivity?, expiry? }
  name?: string                         // the name registered with LiveKit
  worker?: Record<string, unknown>      // extra LiveKit ServerOptions
  prewarm?: (proc: unknown) => void | Promise<void>
}

interface SessionSetup {
  sessionId: string
  scopes?: Partial<Record<SharedScope, string>>
  state?: Record<string, unknown>
  initialState?: StateChanges
  recordingKey?: string                 // overrides the egress object key
  noiseCancellation?: NoiseCancellationType
}

Four of those need explaining. timeouts.inactivity is measured from the last thing that happened, not the last thing the caller said, and it re-arms after every silence. An agent's own timeouts override the handler's, so a transfer can change the clock. sound.noiseCancellation is 'telephony' or 'general', set per handler or per session. recording has two independent halves. dir writes raw tracks locally and mixes them into a WAV on hangup, which is the development one; egress starts a LiveKit room-composite egress straight to S3, which is the production one. And callTermination is on by default: when the call completes the ADK deletes the room, or removes the participant under strategy: 'removeParticipant'. Set it to false when something else owns the hangup.

prewarm runs once per worker subprocess before any call reaches it — the place for tracing setup or loading something heavy, so the first caller does not wait for it.

Step 5

Tools during a call

A tool is the same object in both modes. The voice bridge converts each one into a LiveKit tool carrying the same JSON schema. The executor around it then does what the text runner does: parse the args, run prepare, call execute, run finalize, write a tool_call and a tool_result. Errors go to your error handlers with the same retry, fallback and throw vocabulary. Arguments that fail the schema come back to the model as text rather than throwing, so a bad call is a turn the model can correct.

// Same tool object, either handler. `ctx.voice` is the only voice-only field, and it is
// `undefined` in text mode.
const lookupStay = app.tool({
  name: 'lookup_stay',
  description: 'Look up a booking by its reference',
  schema: z.object({ ref: z.string() }),
  execute: async (ctx) => {
    await ctx.voice?.say('Let me pull that up.')
    return { ref: ctx.args.ref, nights: 3 }
  },
})

// Return a Runnable and the call transfers: LiveKit swaps the agent in place, mid-call.
const toBilling = app.tool({
  name: 'transfer_to_billing',
  description: 'Hand the caller to the billing agent',
  schema: z.object({}),
  execute: () => billing,
})

// The output tool. Calling it ends the call and becomes the run's output.
const endCall = app.tool({
  name: 'end_call',
  description: 'End the call once the caller is done',
  schema: z.object({ summary: z.string(), resolved: z.boolean() }),
  execute: (ctx) => ctx.output({ summary: ctx.args.summary, resolved: ctx.args.resolved }),
})

const concierge = app.agent({
  name: 'concierge',
  model: openai.realtime('gpt-realtime-1.5'),
  context: [app.context.system('Answer booking questions.'), app.context.history()],
  tools: [lookupStay, toBilling],
  output: endCall,
})

ctx.voice is the seam to the audio. It is a small interface on purpose — no LiveKit types cross it:

Both generateReply and say return a VoiceReply, and its one method matters on a phone call: await reply.waitForPlayout() resolves when the caller has heard it. Without it your next line runs while the sentence is still in the air.

Two control signals end a tool differently from a return value. ctx.output(value) makes the value the call's output and starts the hangup — that is what an output tool is, and it is what output: endCall declares. ctx.end() asks to end the call without supplying the value, and requires an output tool to exist, because the handler then runs one more forced generation to collect it. Returning a Runnable transfers instead. The outgoing agent's invocation closes with reason transferred and the incoming agent gets its own invocation_start. Its tools and instructions are rebuilt, and LiveKit swaps the agent inside the live call. The caller hears no seam.

One capability of text mode does not survive the crossing: a tool cannot yield. There is nobody to pause for — the caller is on the line — so Stopping to ask has no voice equivalent. Ask the caller instead.

Step 6

What the ledger records

A call leaves the same kind of event list a text run does, and you read it the same way. Nothing about voice is a special table.

const call = await app.sessions.get('call-4471')

const ledger = call?.events.map((event) => event.type)

// Voice writes the same `user` and `assistant` events a typed turn does, tagged with where the
// text came from.
const transcript = call?.events
  .filter((event) => event.type === 'user' || event.type === 'assistant')
  .map((event) => ({ who: event.type, said: event.text, from: event.source ?? 'text' }))

// Audio tokens ride on the same `model_end` usage a text turn reports.
const audio = call?.events
  .filter((event) => event.type === 'model_end')
  .map((event) => event.usage?.audioInputTokens)

// How the call ended: 'completed' | 'transferred' | 'inactivity_timeout' | 'max_duration' |
// 'disconnected' | 'participant_left'.
const ending = call?.events.findLast((event) => event.type === 'invocation_end')?.reason

The differences are small:

There is no per-turn commit. Events accumulate on the session in memory as the call runs, and the handler writes them once, at the end — after the final hooks, inside LiveKit's shutdown barrier so a hangup cannot outrun it. That is the right trade for a call: a turn is a fuzzy unit here, and the caller is present throughout.

Step 7

Hooks along the call

A VoiceHook is an ordinary Hook — beforeAgent, beforeTool, afterTool, onEvent, all of Guardrails and recovery — plus five callbacks that only a call has. Build one with app.hook.voice and put it in the same hooks array.

const callLifecycle = app.hook.voice({
  // Replaces the default auto-speak on entry and after every transfer.
  onEnter: async (ctx) => {
    const reply = await ctx.voice.generateReply({ instructions: 'Greet the caller by name.' })
    await reply.waitForPlayout()
  },

  // Every transcript line, on its own queue — never blocks the audio pipeline.
  onTranscript: (ctx) => {
    if (ctx.event.type === 'user') ctx.state.update({ lastHeard: ctx.event.text })
  },

  // Return false to keep the call alive, true to end it, nothing for the default end.
  onInactivity: async (ctx) => {
    if (ctx.inactivityCount >= 2) return
    const reply = await ctx.voice.generateReply({ instructions: 'Ask if they are still there.' })
    await reply.waitForPlayout()
    return false
  },

  onExpiry: async (ctx) => {
    const reply = await ctx.voice.generateReply({ instructions: 'Apologise, then wrap up.' })
    await reply.waitForPlayout()
  },

  onDisconnect: () => undefined,

  // Ephemeral telemetry. Never written to the ledger.
  onVoiceEvent: (event) => {
    if (event.type === 'forced_tool_correction' || event.type === 'voice_error') {
      console.warn('[voice]', event)
    }
  },
})

onEnter fires when an agent becomes active — at the start of the call and again after every transfer. Defining it replaces the default greeting, so the first thing the caller hears is yours. onInactivity, onExpiry and onDisconnect share one contract: return false to keep the call alive, true to end it, and nothing at all for the default. When several hooks define the same callback they all run, and any one of them returning false wins — a veto, not a vote. ctx.inactivityCount counts consecutive silences and resets when the agent answers the caller, which is what turns three prompts into an escalation instead of a loop. A sound the agent does not answer, such as a click, keeps the escalation going.

onTranscript runs on its own queue, one line at a time, so a slow hook delays the lines behind it and never the audio. Its context is richer than the others'. Alongside session, state, voice and the event, it carries run(agent, input?) — so a background agent can read the conversation as it happens. A live summary, a check on what was promised, a state update the main agent never has to be told about. State written here is drained before the commit.

onVoiceEvent is the telemetry channel: state transitions, activity markers, lifecycle-hook outcomes, forced-tool corrections, errors. None of it is persisted: it is how the call is behaving, not what happened on it. app.hook.voiceLogging({ level: 'debug' }) is a ready-made hook that formats these as structured log lines.

Step 8

Forcing a tool before speech

Sometimes one specific tool must run before the model is allowed to answer: check the policy before quoting it, record the outcome before hanging up. In text mode that is toolChoice: { name } and the provider honours it. Realtime sessions do not reliably honour a named tool choice. The obvious workaround — hide every other tool for one turn — mutates the tool list, which invalidates the provider's prompt cache. Every turn after that costs more.

So the ADK layers its own guarantee on top of the one thing providers do honour, toolChoice: 'required'. Pass a named tool choice to ctx.voice.generateReply and a gate opens for that generation:

import { ForcedToolCallError } from '@animahealth/adk/voice'

const beforeQuoting = app.hook.voice({
  onTranscript: async (ctx) => {
    if (ctx.event.type !== 'user') return
    if (!/\bcancel\b/i.test(ctx.event.text)) return

    try {
      // The gate: this generation may not end in speech until `check_policy` has run.
      await ctx.voice.generateReply({
        toolChoice: { name: 'check_policy' },
        instructions: 'Check the cancellation policy before answering.',
      })
    } catch (error) {
      if (!(error instanceof ForcedToolCallError)) throw error

      // reason: 'active_gate' | 'exhausted' | 'timeout' | 'generation_failed'
      console.warn(
        `[voice] ${error.intendedToolName} not called (${error.reason})`,
        error.incorrectToolName,
        `${error.attempts}/${error.maxAttempts}`,
      )
      await ctx.voice.say('Let me put you through to someone who can check that.')
    }
  },
})

What the gate does, in order. The named choice is downgraded to 'required' on the way to the provider — the tool list is untouched, so the cache survives. If the intended tool is called, it executes normally and the gate resolves when it finishes. If a different tool is called, that tool never executes: the call is intercepted before beforeTool and before execute, so nothing with a side effect has happened yet. The model gets a synthetic result, and a correction turn goes back naming both the tool it wrongly called and the tool it must call. If the model speaks instead of calling anything, that counts as a wrong answer too; so does calling nothing at all, after a short wait. Each of those consumes an attempt.

When the attempts run out, or the gate times out, or the generation itself fails, the gate clears and rejects. The ForcedToolCallError carries intendedToolName, incorrectToolName, attempts, maxAttempts, source and reason. The same failure is also announced on onVoiceEvent as forced_tool_failure, with forced_tool_correction for each retry along the way.

The gate has three properties you can build on. It is ephemeral — it lives in the voice session for one generation and is never written to session or application state, so nothing to clean up when a call drops. It is exclusive — opening a second gate while one is pending throws immediately with reason: 'active_gate' rather than interleaving two forced turns. And the correction instructions are generic: the ADK will tell the model which tool it must call and will not invent a domain-specific recovery. What to say to the caller when the tool never lands is yours, in the catch.

The same machinery runs on your behalf at the end of a call. Something asks the call to finish: ctx.end(), an inactivity or expiry hook, a caller who hung up. If the agent declares an output tool, the handler triggers one last generation forced onto it, so the structured result is collected before the room closes.

Step 9

Measuring it

A call is hard to assert on: the transcript is nondeterministic and the timing is half the product. The package's answer is app.evaluate.voice, a sibling of the runner in Measuring agents. It puts a second agent on the other end of a real LiveKit room, plays the conversation out, and scores the ledger and the timings it produced. .case, .cases and .report are shaped like their text counterparts, and a control handle can disconnect the simulated caller mid-call. It needs the same LiveKit credentials this chapter's worker does. Follow Evaluate voice agents to build a complete case, assert on tool behavior and response latency, and review the recording.

Step 1

Prepare a local script.

Use Node 22 or later and a LiveKit server. Set LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET, and OPENAI_API_KEY in your local environment. Both sides of the call use a live model, so running the evaluation incurs provider usage.

npm install @animahealth/adk zod@3 @livekit/agents @livekit/agents-plugin-openai @livekit/rtc-node livekit-server-sdk
npm install --save-dev tsx

Create booking-eval.mts and add the following blocks in order. The voice setup guide explains the runtime dependencies.

Step 2

Define the agent and its simulated caller.

This lookup returns synthetic booking data. The same tool could serve a text agent; the realtime model configuration makes this agent speak. Its output tool ends the call.

import { z } from 'zod'
import { adk } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'
import { voiceTimingMetric } from '@animahealth/adk/eval'

const app = adk()
const lookupBooking = app.tool({
	name: 'lookup_booking',
	description: 'Look up a booking by reference.',
	schema: z.object({ reference: z.string() }),
	execute: (ctx) => ({ reference: ctx.args.reference, slot: 'Tuesday 14:30' }),
})
const endCall = app.tool({
	name: 'end_call',
	description: 'End the call after answering the booking question.',
	schema: z.object({ summary: z.string() }),
	execute: (ctx) => ctx.end(),
})

const agent = app.agent({
	name: 'booking-support',
	model: openai.realtime('gpt-realtime-1.5', { voice: 'ballad' }),
	context: [
		app.context.system('Ask for the booking reference, look it up, and tell the caller the slot. Use end_call when finished.'),
		app.context.history(),
	],
	tools: [lookupBooking],
	output: endCall,
})
const caller = app.agent({
	name: 'booking-caller',
	model: openai.realtime('gpt-realtime-1.5', { voice: 'shimmer' }),
	context: [app.context.system('You are calling to check booking B-42. Ask what time it is. When answered, say thank you and goodbye.')],
	tools: [],
})

Step 3

Check the lookup and the response time.

Supply an explicit tool mock so the evaluation controls the lookup result. Let the real output tool end the call. The first metric checks that the agent looked up the requested reference and received the expected result. The second checks the 95th percentile of response latency against an example three-second budget. Choose a budget for your application.

const bookingCase = app.evaluate.voice.case({
	name: 'find-booking-time',
	agent,
	userAgent: caller,
	timeout: 120_000,
	toolMocks: {
		lookup_booking: {
			execute: (args) => ({ reference: args.reference, slot: 'Tuesday 14:30' }),
		},
		end_call: endCall,
	},
	metrics: [
		{
			name: 'looked-up-requested-booking',
			evaluate: (run) => ({
				passed: run.events.some((event) =>
					event.type === 'tool_call' && event.name === 'lookup_booking' &&
					event.args.reference === 'B-42' &&
					run.events.some((result) => result.type === 'tool_result' &&
						result.callId === event.callId && !result.error &&
						JSON.stringify(result.result) === JSON.stringify({ reference: 'B-42', slot: 'Tuesday 14:30' })),
				),
			}),
		},
		voiceTimingMetric({
			name: 'response-within-budget',
			measure: 'response_latency_p95',
			assertion: (ms) => ms < 3000,
		}),
	],
})

The lookup metric verifies tool behavior. It does not establish that the caller heard a correct answer. Review the recording and transcript, and add an outcome metric for the conversational requirement you need to enforce. A timing metric fails when its required measurements are missing.

Step 4

Run the call and review the evidence.

const suite = await app.evaluate.voice([bookingCase], {
	concurrency: 1,
	output: './booking-eval-results',
	hooks: [{
		onEnter: async (ctx) => {
			const reply = await ctx.voice.generateReply({ toolChoice: 'none' })
			await reply.waitForPlayout()
		},
	}],
})

console.log(app.evaluate.voice.report()(suite))
process.exitCode = suite.summary.passed === suite.summary.total ? 0 : 1

npx tsx booking-eval.mts

The evaluation creates a LiveKit room and connects the agent and simulated caller. The console report lists case and metric results. Each case's output directory contains a report.md and recording.wav. The returned case result also includes session events, voice events, a transcript, timing, and usage when available.

Expect the wording and timing to vary between runs. Inspect a failed metric's evidence, then use the recording and events to determine whether the problem was the conversation, a tool, or the connection. A timeout or errored call is not a passing evaluation.

Broaden the cases

Measure the situations your callers encounter.

• Add callers who forget their reference, change their request, or interrupt the agent.
• Use repeat to run each case several times and inspect variation.
• Add time_to_first_speech, silence_gap_max, or interruption_count metrics where they answer a product question.
• Use app.evaluate.voice.case((control) => ...) with control.disconnectUser() to exercise caller disconnection.

Start with the same business outcomes you check in text evaluations, then add audio and lifecycle requirements. Use deterministic tests for tool and state behavior that does not require a live conversation.

Step 1

A call, not a command

The UI is built with ink and React. Both, plus ink-text-input, are optional peer dependencies: the core never pulls them, so install them beside the ADK when you want the terminal.

npm install ink ink-text-input react

The declared ranges are ink 5, ink-text-input 6, and React 18 or 19. The UI is loaded lazily, at the moment you call app.terminal, so a missing one surfaces there — as Terminal dependencies not found. Install them with: npm install ink ink-text-input react, not as a resolver stack trace.

Then the program. app.terminal takes the runnable and, optionally, a first message — it is sent the moment the UI mounts.

// chat.ts
import { adk } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'

const app = adk({ name: 'chat' })

const assistant = app.agent({
  name: 'assistant',
  model: openai('gpt-5.6-luna'),
  context: [app.context.system('Be brief.'), app.context.history()],
})

app.terminal(assistant, 'What is 731 * 268, minus 17?')

npx tsx chat.ts

The third overload takes a config object instead of the message. Everything the UI does is configured there:

const result = await app.terminal(assistant, {
  input: 'What is 731 * 268, minus 17?',
  options: { exitOnComplete: true, showIds: true },
})

process.stdout.write(result.output.text + '\n')

The call returns a handle, not a promise: await it for the RunResult, or read runner, session and runnable off it. The first two are populated once the UI has loaded, so read them after the await — synchronously they are still undefined.

Step 2

What the screen shows

One invocation is one bracketed block: the agent's name on top, its events indented inside, the duration on the bottom. Sub-agents nest as inner blocks. Each model call gets its own model bracket, so a tool-using turn shows two of them.

● debug [d] ○ content [c] ○ logs [l]
 ┌─ booker ◆ agent
  ▸├─ user     book tuesday 3pm
   ┌─ model
     ├─ call     book_slot {"slot":"tuesday 3pm"}
     ├─ yield    book_slot {"slot":"tuesday 3pm"}
     ├─ input    book_slot {"approved":true}
     ├─ result   book_slot → {"booked":true,"slot":"tuesday 3pm"}
   └─ 2ms
   ├─ yield    awaiting 1 call
   ├─ resume
   ┌─ model
     ├─ output   Booked tuesday 3pm.
   └─ 1ms
 └─ 1.9s
scroll [↑↓] • jump [←→] • open [Enter] • close [Esc] • exit [Ctrl+C]

Every line is one event from the session's ledger, under a short label: user, think for reasoning, output for the assistant, then call, yield, input, result and state. Assistant and reasoning text stream in as deltas, with a spinner on the line still being written. ▸ marks the selection, and the footer always names the keys that apply right now.

Three views share that screen, each one key away. debug is everything above. content drops everything but the conversation — user, assistant, reasoning, tool calls and the answers you typed. logs is the console output the UI captured, with a timestamp and level per line, so a chatty tool cannot smear the trace.

○ debug [d] ○ content [c] ● logs [l]
  18:08:42.438 LOG   a log line from the tool
▸ 18:08:42.439 WARN  and a warning
scroll [↑↓] • page [←→] • open [Enter] • exit [Ctrl+C]

One exception governs the whole table: while the prompt has focus, every key is text. Esc hands focus back to the trace, and i returns it to the prompt.

Step 3

Answering a yielded tool

This is the reason to reach for the terminal over console.log. A tool that declares a yieldSchema stops the run and waits for a human. The terminal is that human: the top bar turns up input [i] in yellow, and i opens a form built from the tool's yieldSchema.

Event • yield • ○ clean [c] ○ raw [r] ● input [i]
book_slot yielded
args: {
  "slot": "tuesday 3pm"
}

{
 "approved": ● true ○ false,
 "note": "" ?
}
[↑↓] field • [←→] value • submit [Enter] • cancel [Esc] • exit [Ctrl+C]

↑↓ moves between fields, ←→ toggles a boolean or cycles an enum, strings and numbers are typed, and Enter submits. The answer is delivered to the tool's execute as ctx.input, the run resumes in place, and the ledger keeps yield, input and result as three separate events — the same three the yielding chapter resumes over HTTP.

The form is generated only for a schema the terminal can lay out: at most five fields, each a string, number, boolean, enum or literal — or an array of objects whose fields are those. Anything deeper falls back to one line — Enter result (JSON or string) — parsed as JSON, or taken verbatim if it is not JSON. Optional fields left empty are dropped; required ones fall back to the schema's default.

Step 4

One launch, one conversation

The prompt appears before the first run and after a yielded message — not after a completed one. So a launch is one invocation, plus however many pauses it takes to finish it; when the run completes the UI stays open for reading, and Ctrl+C ends it. Pass exitOnComplete: true to skip the reading.

To get the prompt back after every reply, hand app.terminal a loop that yields — app.loop({ runnable: assistant, yields: true, … }). That is the shape behind examples/assistant.ts, which ends the chat from its while predicate.

import { adk } from '@animahealth/adk'
import { sqliteStore } from '@animahealth/adk/stores/sqlite'

const app = adk({ name: 'chat', store: sqliteStore('./chat.db') })

const id = 'kitchen-table'
const session = (await app.sessions.get(id)) ?? (await app.sessions.create({ sessionId: id }))

await app.terminal(assistant, {
  session,
  input: 'where were we?',
  options: { exitOnComplete: true },
})

await app.sessions.commit(session)
await app.close()

Run that twice and the second launch opens on the first launch's history, because app.context.history() reads the session it was handed. Without the commit, nothing is written and every launch starts empty.

Step 1

Two surfaces, one run

Event is a ledger entry. StreamEvent is everything an Event can be, plus two kinds that only ever exist in flight: assistant_delta and thought_delta. Each carries the delta just produced and the text accumulated so far, so a renderer can append or replace, whichever it prefers.

Deltas are never appended to the session. The runner forwards them from the adapter straight to the observer and drops them; the committed assistant event is written once, after the model call finishes. That is why replaying a session gives you the answer and not the typing.

Observation is a hook. onEvent receives every StreamEvent of a run, in order, and returns nothing — guardrails covers the rest of the interface, including the methods that can interrupt. Below, a registered MockAdapter (testing) stands in for the provider the descriptor names (choosing a model), with streamChunks making it emit the reply in pieces.

import { adk } from '@animahealth/adk'
import { openai } from '@animahealth/adk/openai'
import { MockAdapter } from '@animahealth/adk/testing'

// Every cell below re-scripts this adapter, so cells stay deterministic however often you press Run.
const scripted = new MockAdapter({ responses: [] })

const app = adk({ name: 'streaming', adapters: { openai: scripted } })

const narrator = app.agent({
  name: 'narrator',
  model: openai('gpt-5.6-luna'),
  context: [app.context.system('Answer in one sentence.'), app.context.history()],
})

narrator.name

Now watch one run twice: once through onEvent as it happens, once through run.session.events after it is over.

const streamed: string[] = []
const pieces: string[] = []

// `delayMs` buys the run enough wall-clock to be worth measuring in step 2.
scripted.setResponses([
  { text: 'Chunked on the way out.', streamChunks: true, chunkSize: 6, delayMs: 40 },
])

const run = await app.run(narrator, {
  input: 'Say something.',
  hooks: [
    {
      name: 'watch',
      onEvent: (event) => {
        streamed.push(event.type)
        if (event.type === 'assistant_delta') pieces.push(event.delta)
      },
    },
  ],
})

const surfaces = {
  streamed,
  committed: run.session.events.map((event) => event.type),
  pieces,
  reassembled: pieces.join(''),
  finalText: run.output.text,
}

surfaces

The deltas are in streamed and absent from committed. They arrive before model_end, while the committed assistant event lands after it — the ledger writes the answer once the call is accounted for. And committed opens with a user event that streamed never saw: the message was appended to the session before the run began, so it is history, not this run's stream.

Reassembly is pieces.join('') here, but you rarely need it. Each delta already carries text, the accumulation so far, so a renderer can set its buffer to the latest text and never track state of its own.

Step 2

What a model call cost

One model_start/model_end pair is one round-trip to the provider. model_end is where the money is: stepIndex, durationMs, finishReason, and an optional usage with inputTokens, outputTokens, cachedTokens, cacheWriteTokens and reasoningTokens.

The optionality is the important part, and this cell shows it. durationMs is the runner's own stopwatch around the call, so it is always a number. usage and finishReason come off the provider's response, so a scripted model reports neither — and run.usage, which is rolled up from the model_end events that have usage, is undefined for the whole run. Deterministic tests can assert on latency and call counts; they cannot assert on cost. For cost you need step 5.

import { isModelEndEvent } from '@animahealth/adk'

const perCall = run.session.events.filter(isModelEndEvent).map((event) => ({
  stepIndex: event.stepIndex,
  durationMs: event.durationMs,
  finishReason: event.finishReason,
  usage: event.usage,
}))

const accounting = { runUsage: run.usage, perCall }

accounting

When usage is present, run.usage is the roll-up: modelCalls, the token totals, a models array broken down by model name, and an optional cost of { inputCost, outputCost, totalCost, currency: 'USD' }. The model name is the one you wrote in the descriptor, not whatever the endpoint resolved it to.

No provider sends you a price. The ADK derives one from the token counts and a pricing table internal to the package, so a model the table does not know has no cost field and its token counts stand alone — and a price you negotiated yourself is your own multiplication over those totals.

For the streaming case there is a built-in that does the bookkeeping: app.hook.metrics({ onModelResult }) fires per model_end with the agent name, model name, duration and token counts — one callback into whatever your metrics backend is, with no event filtering of your own.

Step 3

Usage is per session, not per run

Read this before you build a budget on it. The ledger belongs to the session, and run.usage is computed from that whole event list — not from the slice this run appended. That is deliberate: a session accrues its cost and its history as it goes. Give two runs the same session and the second result accounts for both.

const shared = await app.sessions.create()

scripted.setResponses([{ text: 'First answer.' }, { text: 'Second answer.' }])

const firstRun = await app.run(narrator, { session: shared, input: 'One?' })

// The ledger is live, not a snapshot, so measure it now — the second run appends to this array.
const afterFirstRun = firstRun.session.events.length

const secondRun = await app.run(narrator, { session: shared, input: 'Two?' })

const scope = {
  afterFirstRun,
  afterSecondRun: secondRun.session.events.length,
  sessionEvents: shared.events.length,
  modelEndsInSession: secondRun.session.events.filter(isModelEndEvent).length,
}

scope

afterSecondRun equals sessionEvents, and the ledger read from the second run's result holds two model calls after that run made one of them. That total is the conversation's, which is usually what you bill it for. output.text follows the same rule: it is the session's last assistant event. A fresh session per run — which is what app.run creates when you pass a bare string instead of a session — makes every reading a single turn's, so the accumulation only shows once you keep a conversation going. To attribute cost to one turn inside a longer one, diff the session's event list around the run, or accumulate from onEvent: a model_end observed during the run is unambiguously the run's own.

Step 4

Stopping a run

app.run does not take an AbortSignal. It returns a handle — a StreamResult, which is at once awaitable and iterable — and that handle has abort(). Calling it aborts the controller the runner made for this run: the signal is already threaded into the model adapter, so an in-flight provider request is cancelled rather than ignored, and the event channel is torn down. Awaiting an aborted run does not return a result. It rejects, with Aborted.

An AbortSignal you already own connects with one line — signal.addEventListener('abort', () => stream.abort()) — which is what app.ask does with its own signal option, the one place in the API where a signal goes in directly. The cell proves both paths, and both time out well inside the three seconds the scripted model was told to take.

const observed: string[] = []

scripted.setResponses([{ text: 'A reply that never arrives.', delayMs: 3000 }])

const inflight = app.run(narrator, {
  input: 'Take your time.',
  hooks: [{ name: 'watch-abort', onEvent: (event) => observed.push(event.type) }],
})

setTimeout(() => inflight.abort(), 50)

let stopped = 'the run finished first'
try {
  await inflight
} catch (error) {
  stopped = (error as Error).message
}

// The same stop, reached through a signal you own.
scripted.setResponses([{ text: 'Also never arrives.', delayMs: 3000 }])

const controller = new AbortController()
setTimeout(() => controller.abort(), 50)

let asked = 'the ask finished first'
try {
  await app.ask('Anything.', { model: openai('gpt-5.6-luna'), signal: controller.signal })
} catch (error) {
  asked = (error as Error).message
}

const stopping = { stopped, asked, observed }

stopping

observed is where the run got to before it was cut off — the events that had already been produced, and nothing after. Abort is not the only stop, and the others are not interchangeable. app.run(…, { timeout }) races the whole stream and rejects with Timeout after Nms; an agent's maxSteps ends the run with status max_steps instead of throwing; a tool's own timeout is a recoverable phase error. Guardrails is where those live.

Step 5

Real tokens, real money

Everything above ran against a script, so no number in it was a price. This cell calls OpenAI with the key from the box at the top of the page, on a fresh app so the scripted adapter is out of the way. It times the first delta — the number your users feel — and then reads the usage the provider reported.

const liveApp = adk({ name: 'streaming-live' })

const scribe = liveApp.agent({
  name: 'scribe',
  model: openai('gpt-5.6-luna'),
  context: [liveApp.context.system('Answer in two short sentences.'), liveApp.context.history()],
})

const firstDelta: number[] = []
const startedAt = Date.now()

const answered = await liveApp.run(scribe, {
  input: 'What does a hospital ward do at night?',
  hooks: [
    {
      name: 'time-to-first-token',
      onEvent: (event) => {
        if (event.type === 'assistant_delta' && firstDelta.length === 0) {
          firstDelta.push(Date.now() - startedAt)
        }
      },
    },
  ],
})

const measured = {
  msToFirstDelta: firstDelta[0],
  text: answered.output.text,
  usage: answered.usage,
}

measured

msToFirstDelta against durationMs on the model_end event is the streaming argument in two numbers: the reader starts reading at the first, the run ends at the second. The OpenAI adapter always streams, so those deltas arrive whether or not you asked for them — streaming is not a mode you switch on, it is what the transport does, and onEvent is where you decide to care.

Edit the question and run it again to watch the tokens and the cost move. A longer question moves inputTokens; a longer answer moves outputTokens, which on this model is priced six times higher.

Step 6

Getting the stream off the box

A hook is in-process. To reach a browser, the run has to be iterated, and app.handler.turn is the surface for it: it returns a handle that is both an async iterable of stream events and a promise of the committed TurnResult. Driving that handle by hand — and the trap in not doing so — belongs to serving; what is left here is one line down the wire.

// Inside the loop over the turn's stream events.
if (event.type === 'assistant_delta') {
  response.write(`data: ${JSON.stringify({ delta: event.delta })}\n\n`)
}

Forwarding only the deltas is deliberate. The same stream carries a state_change event for every state write, patient and practice scopes included. To send more than text, drop each event for which mayLeaveProcess(event) returns false before it goes down the wire.

For a front end that speaks the AG-UI protocol, app.handler.agui is the same run translated: it hands back an AsyncIterable of AG-UI events, mapping deltas to text-message content frames and tool calls to their protocol equivalents, so a compatible client renders the stream without knowing the ADK exists. Both handlers, and the sessions they commit into, live in serving.

Next: Install and setup — get this on your machine.

2026-10-14

0.6.8

Added

• VoyageModel.timeoutMs and QdrantConfig.timeoutMs — the limit for each provider HTTP request, including reading the response; a whole number of milliseconds from 1 to 3600000, default 30000. A request that runs out fails, and retry decides whether to try again. Any other value throws a RangeError when the provider is created. See vector memory.

Changed

• qdrant() — requests time out after 30s by default instead of the client's 300s.
• voyage() — requests time out after 30s by default instead of the SDK's 60s, which stopped at the response headers, and fail with Voyage request timed out after <n>ms. The SDK no longer retries a 408, 409, 429 or 5xx response itself; retry.maxAttempts is the number of requests.

2026-10-12

0.6.7

A suite's scorecard is one path, recorded with the commit it measured, so the scorecards of several

repositories can be kept in one place. The scorecard declaration from 0.6.6 changes shape in this

patch release: one suite had adopted it, and it moves with this release.

Added

• Scorecards and provenance record judges — each distinct model the cases' metrics reported calling, such as the judge metric's model.
• @animahealth/adk/eval exports parseScorecard and the Scorecard type — the reader every tool shares.
• Scorecards may hold measures — aggregates that are not one case's pass count, each { passed, runs } or { value, n } — with cases or in place of them. The eval CLI writes cases only and rejects a scorecard that has none.
• OpenAIModel.serviceTier: 'flex' — sends OpenAI flex processing requests; a flex request that fails before any output is sent again at the default tier on the same endpoint. Azure endpoints get the default request. See OpenAI.

Changed

• MixedEvalOptions.scorecard: { path, fingerprint } → a path from the top of the outermost repository that holds the working directory — a suite in a submodule records into the repository around it.
• Scorecard files are version 2 — repo (the owner/name the origin remote ends in) and commit replace fingerprint; a reader compares the paths it cares about at that commit.
• Scorecard.cases is optional, and the reader rejects a key the format does not name.
• Eval CLI run --record needs the scorecard's directory to exist, an origin remote and the whole checkout committed, submodules aside, before any case runs, and records nothing when HEAD moves or the checkout changes during the run.
• provenance.fingerprint is removed; provenance.dirty covers the whole checkout, submodules aside, for every suite.

Migration from 0.6.6

Scorecard declaration and file

Replace scorecard: { path, fingerprint } with scorecard: '<path>', from the top of the outermost

repository. A version 1 scorecard at that path is rejected before any case runs, so --record

cannot replace it. Delete the file, commit the deletion and record again with --record; or replace

its fingerprint with repo and the commit whose ids for those paths are the recorded ones, and

set version to 2.

2026-10-08

0.6.6

Added

• MixedEvalOptions.scorecard: { path, fingerprint } declares a committed eval CLI baseline with per-case pass counts, Git file IDs, runner, and models. Keep it in the same repository as its fingerprint paths, but outside them. See Eval scorecards.
• Eval CLI run --record replaces the declared scorecard with exactly the selected cases. It requires clean fingerprint paths and preserves the scorecard if the run stops early, a case errors, times out or aborts, or fingerprinted files change during the run. result.json reports record: { file, written }; exit code 0 means the scorecard was written.
• Eval CLI run compares with an existing declared scorecard unless --baseline is supplied, reporting its recording date and whether fingerprint paths still match. Scorecards require a cases field and contain no tool results, so comparison.toolResults is absent for these comparisons.
• Eval CLI --kind text|voice filters cases alongside --case. An empty selection exits with code 2.
• result.json includes provenance: runner, models, available Git commit and dirty state, and declared fingerprints. Suites without scorecards still run when Git is unavailable.

2026-10-08

0.6.5

Added

• Hook.duringModel(ctx, renderCtx, signal) runs alongside the model call. A hook answer that wins the race replaces the model's step and cancels the call. If the hook declines, rejects, or answers late, the model's step stands. The hook's signal aborts when its answer can no longer be used. Model events are buffered until the hook settles or the model step completes. See Hooks.

2026-10-07

0.6.4

Added

• app.decide(input, { questions, model?, signal? }) answers closed questions (predicate, choice, score) on the model's decisions endpoint, with probabilities. See One-shot calls.
• DecisionsUnavailableError rejects it for a model no decisions endpoint serves; today only OpenAI gpt-6-luna is served. There is no fallback to a model call.
• ModelAdapter.decide is the optional adapter method behind it; MockAdapter scripts it with decisions and fails an unscripted question.
• Eval CLI --baseline <run> (repeatable, pooled) compares a run with earlier ones — each case is regressed, improved, unchanged or unclear by a two-sided Fisher exact test on its pass counts, and tool results that one side returned and the other never did are listed. The comparison follows the summary in report.md and is comparison in result.json.
• Eval CLI --case may repeat.
• A text case's case-<n>.json has modelInputs and instructions — the system messages, toolChoice and allowedTools each model call was given.

2026-10-06

0.6.3

Added

• LiveVoiceHook.onVoiceActivity reports speaking, transcript, backend-run and silence events. Its context exposes sinceRun and runBackend() to process caller speech not yet given to a run. The trigger returns false when a run is active, no speech is pending, or the call has ended.
• Silence-timeout activity hooks can await before triggering a run. The handler holds the silence timer and waits up to backendTimeoutMs; a run started during that wait replaces the silence response. Other activity events do not wait for hook promises.
• GPT Live supports sound.backgroundAudio.thinking while delegations are pending, pausing for completed answers and resuming for remaining work. Playback failure leaves the call running without sound. Voice eval callers still hear only the agent's microphone track, not the thinking sound.
• LiveVoiceDelegation.startedBy says what started a GPT Live backend run: voice for GPT Live's delegation, handler for the silence rule, app for a hook's runBackend(). Hooks read it on ctx.delegation and on run_started and run_settled activity, so an app can tell its own trigger's run from the silence rule's without parsing the run's ID.

Fixed

• Package export verification can invoke npm on Windows.

Internal

• The silence rule that runs undelegated caller speech goes through the same trigger as runBackend(); its behaviour is unchanged.
• The ADK guide explains how to keep context prefixes stable for provider prompt caching.
• Stream regression tests cover nested runs, parallel branches, timeouts and aborts.

Migration from 0.6.2

Code that builds a LiveVoiceDelegation itself, such as a test double given to a hook, must set startedBy.

2026-09-30

0.6.2

Added

• LiveVoiceControls.untilQuiet() waits for non-interruptible commentary to finish or reach its playout bound. Use it before a transfer that must follow a notice; it does not confirm the caller heard the notice.
• GPT Live supports call recording through recording and setup().recordingKey, and caller noise cancellation through sound.noiseCancellation.
• app.replyTool and ReplyToolConfig let a tool call serve as the agent's reply without forcing an exit.
• OpenAIModel.parallelToolCalls: false disables parallel tool calls on the Responses API.
• LiveContentFilterError, exported from /voice, reports moderation stops to GPT Live onError hooks after reconnection. It is recoverable and has no delegation.

Changed

• Non-interruptible GPT Live commentary waits for quiet, not in-flight delegations or earlier commentary to start. Combine a notice and its preceding commentary into one line when their order matters.
• GPT Live groups consecutive caller transcript fragments on each connection, up to the next delegation, into one user event in backend history and voice evals. liveTranscript retains raw fragments.
• Voice eval evidence uses one run clock through atMs; simulated callers can delegate without failing the case.
• OpenAIRealtimeTextAdapter uses the GA Realtime API and no longer sends temperature. Optional ModelAdapter.endInvocation releases resources when an invocation ends, including on a tool call.

Fixed

• GPT Live reconnects reuse the in-flight backend result for the same caller turn, preventing duplicate tool actions. Interrupted result and error hooks are not replayed.
• Moderation recovery starts a fresh connection without replaying the blocked conversation and drops commentary interrupted by the disconnect.
• Pending non-interruptible commentary suppresses silence prompts, settles if delivery fails, and no longer delays caller hangup. Invalid noise-cancellation modules fail at call startup.
• GPT Live error logs omit messages and stacks that could contain caller speech.
• Voice eval recording uses the participants' own rooms to avoid missing audio tracks. Evidence preserves safe error fields, omits function-valued state properties, and identifies invalid JSON values by path.
• Output coercion handles repeated union values independently instead of treating them as cycles. Output tools run even when omitted from the agent's tools list.
• MCP installs process signal handlers only after an MCP server is added, leaving other hosts' shutdown handling untouched otherwise.
• GPT Live logs each provider error event as Live provider error with its type and code only, never its message, so moderation stops and other provider failures are visible.
• A caller turn GPT Live transcribes but never delegates is run on the backend when the silence timer fires, instead of a silence prompt, so the call no longer ends on silence.

Migration from 0.6.1

Custom implementations and mocks of LiveVoiceControls must implement untilQuiet(): Promise<void>. ADK-provided controls already implement it. Realtime consumers must use GA-compatible models and must not rely on temperature taking effect.

2026-09-28

0.6.1

Adds GPT Live, richer evaluations, self-hosted model adapters and Zod 4 support. Review the migration notes before upgrading from 0.6.0.

Added

• [GPT Live](docs/gpt-live.md) — openai.live('gpt-live-1', options) connects voice agents to ADK backends, with tools, persisted state, transcripts, lifecycle hooks and cost tracking. Commentary supports interruption control, not guaranteed verbatim speech.
• Evaluations — app.evaluate.cli runs mixed text/voice suites with simulated callers, JSON evidence and pass/fail exit codes; app.evaluate.judge adds [model-judged metrics](docs/judge-metric.md) with separate judge costs. /eval exports liveTranscriptTurns for speaker-turn grouping.
• Model adapters — /chat-completions and /eurouter support self-hosted endpoints, streaming, tools and structured output.
• run.settled — await execution and cleanup before committing or closing a session store.

Changed

• Schema compatibility — supports Zod 3 Classic ^3.25.76 and Zod 4 Classic ^4.6.5.
• Provider compatibility — accepts matching LiveKit agents/plugins from 1.4.4; GPT Live requires Agents and the OpenAI plugin 1.9 or later. OpenAI requires ^6.0.0, Google GenAI ^1.52.0, and @livekit/rtc-node is an explicit optional peer.
• Naming — use app.terminal, /terminal, Terminal*, app.hook.console, consoleHook and ConsoleHookOptions. All previous CLI names, imports and types remain deprecated aliases.
• Pricing — estimates use LiteLLM's live catalog; configurePricing(options | false) overrides or disables it. Cost-summary helpers accept a catalog, and unavailable prices leave costs unknown.
• Streams, hooks and adapters — include nested runs, notes, yields and state changes consistently; REST and AG-UI filter process-local events. See migration notes for forwarding and hook timing.
• Eval reports — preserve partial costs and running results after failures. Metric data must be JSON-compatible, report cases require run, and voice configuration moves under options.voice. Use returned evidence paths or index.md.

Fixed

• Execution — correct nested-run status, errors, state callbacks and yielded-tool resumption. Calls after an output or transfer receive error results without running, preventing unanswered-tool errors.
• Voice — silence timers exclude speaking time and expose user_speech_ended; see the changed inactivity-count semantics below.
• Providers and schemas — correct cache/audio/thinking-token costs, preserve EUrouter reasoning and Zod wrapper metadata, support OpenAI reasoning.effort: 'none' with temperature, and parse wrapped primitive outputs correctly.
• Packaging — exclude generated caches, restore standalone test typechecking, and declare the existing ctx.note API.

Migration from 0.6.0

Stream forwarding and hooks

Run and turn-handler streams now include state_change for every scope. Before forwarding events outside the process, filter with mayLeaveProcess; REST and AG-UI already do so. Annotations are forwarded, so avoid patient data in ctx.note.

Hooks receive parallel events when branches settle and only state changes owned by their run's invocations. They continue observing unfinished spawned/dispatched work after a parent yields or fails. Use the new session.addStateChangeListener for direct session writes or other runs; custom Session implementations must implement it.

REST consumers should group nested events by invocationId and parentInvocationId. AG-UI consumers should use tool results rather than expecting nested agents' text in the conversation.

InvocationContext.onStream and ToolContext.onStream are removed. Return tool data or use ctx.note for annotations.

Metrics and pricing

Return passed: false for a product failure; thrown metric errors now produce status error, not failed. Treat missing cost as unknown, not zero; configure a reachable price map or disable estimation.

Silence count

inactivityCount resets when the agent replies, not on caller sounds or silence prompts. GPT Live requires a separate audio burst, with an 800 ms pause, to count a new reply. If an inactivity hook keeps the call open without speaking, the next reply counts as its prompt unless the handler skipped that hook. Review fixed-count hangup hooks against these semantics; see [GPT Live](docs/gpt-live.md).

2026-09-01

0.6.0

The first public release. It removes untested experimental APIs and restores the supported local storage integrations.

Added

• SQLite storage — restored SQLiteStore, sqliteStore(), and vector memory through sqliteVec().
• Built-in hooks — exported composeHooks, loggingHook, metricsHook, and cliHook from the main entry.
• Storage contracts — added shared compliance suites for session stores and vector indexes.

Changed

• zod — raised the peer floor to ^3.25.0 and rejected Zod 4 schemas with a clear error.
• Model adapters — applied adk({ adapters }) to run, handler, voice, and CLI entry points.
• Provider SDKs — kept imports lazy and declared the packages as optional peers.

Fixed

• Stores — fixed concurrent lazy initialization, duplicate events, filtered SQLite vector search, and side effects from read-only pgvector operations.
• Postgres and DynamoDB — fixed string-valued Postgres state and implemented DynamoDBStore.list().
• Optional dependencies — added clear missing-package errors for CLI, SQLite, and web packages.
• Test kit — shipped /testing matcher types and allowed model('text') replies.

Removed

• Experimental APIs — removed executors, gateway, process-store, artifact, channel, and knowledge APIs.
• Obsolete fields — removed RunResult.stepEvents and FunctionTool.requiresApproval. Read events from run.session.events and use yielding tools for approval.

2026-08-20

0.5.27

Added

• OpenAI explicit prompt caching — configure OpenAIModel.promptCache and mark the stable prefix with app.context.cacheableUser(...); Responses API cache reads and writes are exposed through ModelUsage and UsageSummary.

2026-06-08

0.5.25

Republish of 0.5.24 with a packaging fix — no API or runtime changes.

Fixed

• Published manifest — @types/node now publishes as a concrete range (^22.19.19) instead of the raw pnpm catalog: token. 0.5.24 shipped "@types/node": "catalog:", which broke pnpm pack / pnpm install for anyone consuming the package outside the workspace it is published from, with ERR_PNPM_CATALOG_ENTRY_NOT_FOUND_FOR_SPEC.

Internal

• Publish pipeline — adk-publish.yml now packs with pnpm pack (which resolves catalog: / workspace: specifiers) and uploads the resulting tarball with npm publish, so the published manifest no longer leaks workspace-only specifiers while keeping npm OIDC trusted publishing. Publishing the source directory with npm publish shipped package.json verbatim, which is how the catalog: token reached 0.5.24.

2026-06-04

0.5.24

Workflows: author Claude Code-style .workflow.js files and run them through the ADK, plus a few general additions used to express them.

Added

• @animahealth/adk/workflow — runWorkflowFile() runs a CC-style workflow file through app.run, binding agent() to a configurable node runner (default app.ask; a CodingAgent over a provisioned workspace for build attractors).
• app.ask(prompt, opts) — terse, typed one-shot LLM call (no tools, fresh session); options typed as AskOpts.
• fanout(thunks, { limit }) — capped isolated concurrency; a failed thunk resolves to null.
• AnnotationEvent + ctx.note() — generic progress events (phase() / log() are sugar over ctx.note()).

Changed

• Voice handler — end-of-invocation hooks (afterAgent/afterTurn) now run inside LiveKit's shutdown barrier, so completion side effects (e.g. completeCall) run exactly once before the worker exits — even on abnormal teardown (caller disconnect, human transfer, drop). Previously they were skipped if the job was killed before the post-sessionDone path ran.
• Voice handler — fixed shutdownProcessTimeout unit bug (60ms → 60_000ms / 60s, matching LiveKit's default); the worker was force-killing job processes ~60ms into shutdown, before finalization could complete.
• Voice handler — beforeAgent returning a string now finalizes through the same shared path as any other call (completion hooks run), replacing a separate early-exit lifecycle.

2026-05-26

0.5.23

Added

• Voice lifecycle diagnostics — added typed voice activity and lifecycle hook events to production/eval voice handlers, voiceLoggingHook, and voice eval reports.
• Voice playout tests — covered ctx.voice.generateReply() plus reply.waitForPlayout() from inside tool execution, including LiveKit awaitable speech handles.

Changed

• LiveKit voice peers — raised @livekit/agents and provider plugin peer floor to ^1.4.4, and bumped @livekit/rtc-node to ^0.13.28, verified with child speech-handle playout waits inside tool execution.

Fixed

• Voice output tools — model-initiated output-tool completion now stores the structured output internally without returning it to the realtime model, preventing final summaries from being spoken as a trailing assistant response.

2026-05-20

0.5.22

Voice output completion is now a visible, typed lifecycle step. Named voice tool forcing is handled inside the ADK without mutating the realtime tool list, so voice agents can reliably collect final structured output while preserving provider prompt caches.

Added

• Voice forced-tool gate — ctx.voice.generateReply({ toolChoice: { name } }) now enforces the named tool internally while sending provider-compatible toolChoice: "required".
• Voice output completion telemetry — added output_tool_completion_started, output_tool_completion_succeeded, output_tool_completion_failed, forced_tool_correction, and forced_tool_failure voice events.
• Voice diagnostics — eval reports now include forced-tool and output-completion timelines with timestamps relative to case start.
• Voice errors — exported ForcedToolCallError and OutputToolCompletionError from @animahealth/adk/voice.
• Voice forced-tool gating — cache-stable named tool forcing is now a specified contract rather than an implementation detail.

Changed

• Voice ctx.end() — ending tools now return their tool result before ADK forces the configured output tool and then shuts down the voice lifecycle.
• Voice output tools — output-tool completion timeout/failure is no longer treated as silent success; eval paths surface typed failures and production emits diagnostic voice events.
• Voice eval cleanup — teardown now uses bounded waits for tracker flush, LiveKit session close, recorder stop/disconnect, room disconnect, and room deletion.

Fixed

• Voice forced tools — wrong tools are intercepted before tool execution and before app beforeTool hooks, then corrected after the synthetic wrong-tool result is returned to the provider.
• Voice forced tools — required generations that produce no tool call now retry with a generic correction naming no_tool_call and the intended tool.
• Voice shutdown — after-turn hooks, session commit, and call termination now run in a stable order after output finalization.

Migration from 0.5.21

Voice output completion failures

Voice evals can now fail when the configured output tool is not actually completed. This is intentional: missing final structured output is now observable instead of being treated as best effort success. Production cleanup still runs after output completion failure.

Named voice tool choices

Applications no longer need app-level generic "wrong tool redirect" state for voice toolChoice: { name }. Keep domain-specific fallback logic in the application, but let the ADK own generic named-tool enforcement.

2026-05-19

0.5.21

Added

• Voice evals — app.evaluate.voice.case((control) => case) now exposes control.disconnectUser(), letting eval code orchestrate caller disconnects from hooks, tool mocks, or other TypeScript code.

Fixed

• Voice handlers — participant disconnect, inactivity, expiry, and ctx.end() paths now wait for the output tool to complete before room termination.
• Voice evals — transcript hooks now run in the voice harness, and participant-left cases can pass/fail on metrics after cleanup instead of always reporting as terminated.

2026-05-17

0.5.20

Fixed

• Voice handlers — lifecycle hooks (onInactivity, onExpiry, onDisconnect) now run the active agent hooks together with handler hooks, matching voice eval behavior and allowing agent-owned inactivity prompts in production.
• Voice evals — expiry timeouts now run onExpiry hooks before ending the case, matching production timeout behavior.
• Artifact sync — file-watch artifact watchers now perform the documented final sweep on stop(), so missed filesystem watch events are still collected.
• Memory evals — the network-backed Voyage embedding eval now requires ADK_RUN_VOYAGE_EVALS=1 in addition to VOYAGE_API_KEY, keeping default test and publish runs offline.

Internal

• Package publishing — @animahealth/adk now publishes from this package's own source tree, with repository metadata to match.

2026-05-08

0.5.19

Fixed

• Voice handlers — forced output-tool replies now wait for speech playout before ending the LiveKit room.

2026-05-08

0.5.18

Fixed

• Voice generateReply() — preserves the entry-reply scheduling yield after capturing LiveKit's synchronous speech handle so onEnter replies do not race realtime session instruction updates.

2026-05-05

0.5.17

Fixed

• Voice handlers — ctx.end() from a voice tool now waits for the model-triggered output tool and current playout to finish, then deletes the LiveKit room by default; use callTermination: false to leave hangup to the deployment.
• Voice generateReply() — LiveKit speech handles are now captured synchronously, named tool choices use LiveKit's { type: 'function', function: { name } } shape, and undefined tool results stay undefined instead of being coerced to an empty string.

2026-03-26

0.5.16

Changed

• waitForPlayout — added to ToolExecutionContext and MockToolContext; removed broken session-level VoiceSession.waitForPlayout(). Use ctx.waitForPlayout?.() in tools, reply.waitForPlayout() in lifecycle hooks.

Fixed

• dynamoStore — unused ExpressionAttributeNames on non-create commits caused ValidationException.
• dynamoStore — scoped-state pk separator changed from _ to # to prevent collisions when scopeId contains underscores. (unused in production currently)

2026-03-26

0.5.15

Fixed

• dynamoStore — support custom key schemas via partitionKey / sortKey config options (defaults to pk / sk for backwards compat).

2026-03-24

0.5.14

Fixed

• Coercion parser — use _def.typeName instead of instanceof so coercion works across Zod instances.
• Voice tool bridge — pass JSON Schema to LiveKit; validate with coercion in the ADK executor.
• {} on optional primitive fields now coerces to undefined.

2026-03-24

0.5.13

Fixed

• Tool arg validation — run args through the coercion parser before safeParse, so malformed values are coerced instead of silently failing. Applies to all agent tool calls, yielding tools, and the LiveKit voice bridge.

2026-03-21

0.5.12

Fixed

• Handler session key — resolveSession used agent.name instead of the app name; app.sessions.get() could never find handler-created sessions. HandlerConfig.appName is now required (app.handler.* injects it automatically).

Removed

• session.truncateAt() — broke commitSession (cursor divergence). Use session.forkAt() instead.

2026-03-20

0.5.11

Added

• session.truncateAt(eventIndex) — truncate event history in-place; unlike forkAt, mutates the same session.
• Memory sample() — large candidate pools now bypass the server-side distance matrix and compute diversity locally from raw vectors.

2026-03-20

0.5.10

Fixed

• toolInputsSchema() — generated schema field data → input to match ToolInput consumed by applyInput().

Added

• RestResponse.state — rest handler returns session state when response.state is enabled.

2026-03-17

0.5.9

Added

• Voice eval reports now include per-model-call cost and token breakdown.

Fixed

• A single voice eval worker crash no longer aborts the entire suite.
• ctx.end() from the output tool no longer loops indefinitely.
• Orphaned eval workers handle EPIPE, closed IPC, and upstream currentGeneration throws gracefully.

2026-03-16

0.5.8

Added

• toolMocks — output tools (agent.output) are now intercepted the same as regular tools; unmocked output tools throw EvalToolError when toolMocks is provided.

2026-03-16

0.5.7

Fixed

• Voice eval — requireLiveKit() await import() → require() to fix dual-package hazard that silently prevented conversations from starting.
• Voice eval report — stale speech end timestamps from previous segments no longer produce backwards time ranges.

2026-03-15

0.5.6

Changed

• openai, gemini, claude, voyage, qdrant — import from @animahealth/adk/openai, /gemini, /claude, /voyage, /qdrant instead of the main entry.

```typescript

// Before

import { adk, openai, voyage, qdrant } from '@animahealth/adk'

// After

import { adk } from '@animahealth/adk'

import { openai } from '@animahealth/adk/openai'

import { voyage } from '@animahealth/adk/voyage'

import { qdrant } from '@animahealth/adk/qdrant'

```

2026-03-14

0.5.5

Changed

• All optional dependencies (openai, @google/genai, @anthropic-ai/vertex-sdk, pg, @qdrant/js-client-rest, voyageai, ws, etc.) — require() → async import() so bundlers can tree-shake unused providers.
• sqliteIndex(dbPath) — now returns Promise<VectorIndex>; callers must await.

2026-03-08

0.5.4

Added

• app.hook.voice() — typed entry point for custom voice hooks; accepts Partial<VoiceHook<S>> and returns VoiceHook<S>. Mirrors app.hook() for standard hooks.
• VoiceHook.onTranscript — fires for each user or assistant transcript message with full context (session, state, voice, event) and ctx.run() for text-mode sub-agent orchestration. Runs in a dedicated queue that never blocks the voice pipeline; drained before session commit so in-flight state mutations are preserved.
• VoiceSession.turnCount — number of user speech segments (blocks of continuous user speech). Incremented each time the user starts speaking. Use ctx.voice.turnCount > 0 to determine if the caller has engaged.
• Output tool auto-trigger — when an agent has an output tool and turnCount > 0, the ADK automatically triggers it via generateReply({ toolChoice: 'required' }) on lifecycle events (disconnect, inactivity, expiry). Hooks no longer need to manually force the output tool.
• ctx.end() — synchronous control signal (like ctx.output()) that triggers the agent's output tool via the model. Return it from a tool's execute to end the session with model-generated output: return ctx.end(). Voice mode triggers generateReply; text mode sets endInvocation.
• ctx.run() / ctx.spawn() / ctx.dispatch() in voice mode — voice tools can now run text-mode sub-agents inline. Backed by BaseRunner; the sub-agent runs in the same session while the voice session continues.
• VoiceHandlerConfig.prewarm — optional per-subprocess init callback, called by LiveKit before any job runs (e.g. Sentry, OpenTelemetry setup)
• Schema defaults — Zod .default() values declared in stateSchema are now applied to initial state across all entry points (voice setup, REST/AG-UI handlers, app.run(), test runner, voice evals). Setup functions no longer need to manually mirror defaults.
• SessionSetup.noiseCancellation — per-session noise cancellation profile set in setup(). Overrides handler-level sound.noiseCancellation when present.
• app.evaluate.report(options?) — factory that returns (result) => string. Configure once, call with any eval result. Replaces app.report(result, options).
• app.evaluate.voice.report(options?) — voice-specific report factory with narrowed types; renderCase receives VoiceEvalCaseResult with run.transcript, run.timing, run.recording.
• BaseEvalCaseResult / BaseEvalResult — shared base types for text and voice eval results; EvalCaseResult and VoiceEvalCaseResult both extend BaseEvalCaseResult.
• ReportOptions<S, R> — now generic over result type R; renderCase, sections, and footer callbacks receive the correct result/case types.
• MetricResult.data — optional Record<string, unknown> for attaching arbitrary structured data (computed values, intermediate measurements, debug info) to metric results.
• app.evaluate.case() / .cases() / .metric() — identity helpers for type-safe eval config definition; provides schema inference without runtime overhead.
• app.evaluate.voice.case() / .cases() — identity helpers for voice eval cases.
• app.initialState() — identity helper for typed multi-scope initial state config.
• MockToolContext.voice, .output(), .end(), .run() — expanded mock context surface; tool mocks can now test voice state, output signals, end signals, and sub-agent handoffs.
• Input.initialState / SessionSetup.initialState — multi-scope state seeding via handler input and voice setup; seeds session, user, patient, practice, org, team scopes in one call.
• EvalOptions.repeat / VoiceEvalOptions.repeat — run each case N times; results carry repeatIndex and repeatTotal metadata. Reports auto-group repeated cases with pass-rate summaries.
• BaseEvalCaseResult.repeatIndex / .repeatTotal — present when repeat > 1; structured repeat metadata replaces name-mangled [i/n] suffixes.
• Voice eval process isolation — when concurrency > 1, each voice eval case auto-forks into its own child process with an independent event loop and native thread pool. Eliminates WebRTC contention at high concurrency.

Changed

• Generic parameter order — Agent<TOutput, S> → Agent<S, TOutput> (and AgentConfig, OutputConfig, RunResult, AgentSpec); Agent<unknown, MySchema> simplifies to Agent<MySchema>
• ctx.output() in voice mode — output signal is ignored when turnCount === 0 (no user engagement). A voice session with no user turn cannot produce meaningful output; the session ends through the lifecycle event (disconnect, inactivity) instead of completed.
• SoundConfig.noiseCancellation — boolean | unknown → 'general' | 'telephony'. Resolves to BackgroundVoiceCancellation or TelephonyBackgroundVoiceCancellation from @livekit/noise-cancellation-node internally. Replace true with 'general'.
• VoiceEvalOptions.room — now optional; defaults to LIVEKIT_URL / LIVEKIT_API_KEY / LIVEKIT_API_SECRET env vars.
• Voice eval default timeout — 480s → 300s (5 min).
• StateChanges<S> — now generic over state schema for typed multi-scope seeding.
• MetricRun<S> — now generic over state schema; Metric<MetricRun<S>> provides typed session access.

Removed

• app.report() — use app.evaluate.report() instead
• repeatCases() — use EvalOptions.repeat / VoiceEvalOptions.repeat instead
• parseRepeatName() — repeat metadata is now structured (repeatIndex, repeatTotal) on result objects

Fixed

• Voice thinking sounds — pre-decoded into memory at session start; eliminates ffmpeg subprocess spawn and stutter on first play
• Voice handler cleanup — cancel speech wait and stop thinking sound on session end; prevents dangling timers after disconnect.
• Voice handler lifecycle — state guard before beforeEnd callback prevents double-end race when multiple lifecycle events fire concurrently.
• Voice handler transcript drain — 10s timeout cap prevents hanging when the transcript queue stalls on disconnect.
• Voice eval inactivity timer — now resets on agent activity and fires onInactivity hooks, mirroring production handler behavior.

Migration from 0.5.3

Generic parameter order: <TOutput, S> → <S, TOutput>

```typescript

// Before

Agent<unknown, typeof schema>

Agent<string, typeof schema>

// After

Agent<typeof schema>

Agent<typeof schema, string>

```

app.report() → app.evaluate.report()

Report is now a factory — configure options up front, call the returned function with a result. This lets you define reports in a separate file without having the result available.

```typescript

// Before

const md = app.report(result, { title: 'My Eval' })

// After

const report = app.evaluate.report({ title: 'My Eval' })

const md = report(result)

// Voice — renderCase receives VoiceEvalCaseResult with full inference

const voiceReport = app.evaluate.voice.report({

renderCase: (r) => r.run.transcript.map((t) => t.text).join('\n'),

})

```

2026-03-05

0.5.3

Voice evaluation framework — run voice agents through real LiveKit rooms with a simulated user agent, collect transcripts and timing data, and measure outcomes with voice-specific metrics.

Added

• evaluateVoice(cases, options) — runs VoiceEvalCase[] through LiveKit rooms with real audio; returns VoiceEvalResult with per-case transcripts, timing, recordings, and metrics
• VoiceEvalCase — defines agent under test, simulated userAgent, optional toolMocks, per-case metrics, retries, and timeout
• VoiceEvalOptions — suite config: room (LiveKit URL + credentials), output directory for per-case reports and recordings, concurrency, stopOnFirstFailure, onCase progress callback, and suite-level metrics and hooks
• VoiceRunResult — run output with transcript: TranscriptEntry[], timing: VoiceTiming, recording: { path }, events, session, usage, and durationMs
• VoiceTiming — timing data: timeToFirstSpeechMs, responseTimes, silenceGaps, interruptions (count, byAgent, byUser), vadResolutionMs
• voiceTimingMetric(config) — metric factory for voice timing measures: time_to_first_speech, response_latency_p50, response_latency_p95, response_latency_max, silence_gap_max, silence_gap_total, interruption_count
• createSpeakerTracker() — tracks agent/user speech segments for transcript and timing computation
• TranscriptEntry — { role, text, startMs?, endMs?, turnIndex }
• ToolContext.waitForPlayout — opt-in helper for tools that need to wait for pending agent speech to finish
• VoiceHook.onEnter — fires when an agent becomes active (initial entry and after transfer); replaces default auto-speak when defined
• Voice handler auto-speak — calls generateReply({ toolChoice: 'none' }) on agent activation when no onEnter hook is defined

Changed

• Voice handler onEnter — no longer auto-speaks when no hooks are defined; add an explicit onEnter hook to greet the caller
• VoiceEvalOptions.recording → VoiceEvalOptions.output

Fixed

• Voice thinking sounds — deferred until agent speech playout completes; tool execution itself is not blocked
• Voice inactivity timer — resets on actual speech start instead of transcript arrival; no longer fires while agent is thinking or speaking

Removed

• Agent.greeting, GreetingContext — move greeting content into system prompt; use onEnter for ephemeral instructions

2026-03-02

0.5.2

Internal

• Fix ESM require() shim — inject createRequire banner in tsup ESM output so lazy require() calls resolve correctly (fixes "Dynamic require of X is not supported")
• Remove lodash dependency — isEqual → node:util.isDeepStrictEqual

2026-03-01

0.5.1

Realtime voice agents — OpenAI and Gemini realtime adapters, LiveKit voice handler, native agent yield/resume loops with greeting and timeout support, structured session completion via output tools, and app-owned session management.

Added

• realtime() / openai.realtime() / gemini.realtime() — wraps a provider model for realtime use; text-mode agents use native WebSocket adapters, full audio pipeline (with stt + tts) falls through to the standard adapter
• @animahealth/adk/voice subpath — LiveKit voice handler; ctx.voice (VoiceSession) available in tools for generateReply, waitForPlayout, interrupt; app.handler.voice(config) on the handler namespace
• OutputConfig accepts a FunctionTool — pass app.tool() as agent.output for tool-injection output mode; framework injects the tool, validates args, runs execute, captures output, and manages shutdown
• VoiceHook — extends Hook with onInactivity, onExpiry, onDisconnect lifecycle callbacks; defined inside the unified hooks array on VoiceHandlerConfig. Return false to keep session alive, true to explicitly end. Multiple hooks compose: any false vetoes end
• VoiceHandlerConfig.timeouts — handler-level { inactivity?, expiry? } defaults; per-agent timeouts override them after transfers
• VoiceSession.generateReply() accepts full ToolChoice — adds 'required' and { name: string } for forcing specific tool calls in lifecycle hooks
• Agent.yields — yield for user input after terminal model output instead of completing; defaults to true for realtime models. Agent.maxTurns caps yield/resume cycles (default: 100; produces status: 'max_turns')
• Agent.greeting — string or (ctx: GreetingContext) => string | Promise<string>; injected as system event on first activation only, not on resume
• Agent.timeouts — { inactivity?, expiry? } in ms; produces status: 'inactivity_timeout' or status: 'max_duration'
• ctx.output(value) on ToolContext, ToolExecutionContext, StepContext — ends the invocation early; value becomes RunResult.output.value
• adk({ store }) — optional SessionStore on the app factory; defaults to in-memory. app.sessions exposes create, get, delete, list, commit, merge pre-bound to the app name
• inMemoryStore(), dynamoStore(), sqliteStore(), postgresStore() — store factory functions; class constructors deprecated
• UsageSummary.models — per-model ModelUsageEntry[] with calls, token counts, and per-model cost. ModelUsage gains audioInputTokens, audioOutputTokens, audioCachedTokens for realtime models
• UserEvent.source, AssistantEvent.source — 'text' | 'transcript' distinguishes direct text from audio transcription
• Realtime model pricing — gpt-realtime-*, gpt-4o-realtime, gpt-4o-mini-realtime, gemini-*-native-audio, gemini-live-*
• @livekit/agents, @livekit/agents-plugin-openai, @livekit/agents-plugin-google — optional peer dependencies

Changed

• ctx.call() → ctx.run(), CallResult → SubRunResult, CallResultTransfer → SubRunResultTransfer — old names are deprecated aliases until 0.6.0
• AgentTimeouts.maxDuration → AgentTimeouts.expiry (deprecated alias maxDuration still works)
• ModelEndEvent.modelName → ModelUsage.modelName — model name now lives on the usage object; code reading event.modelName on model_end events must switch to event.usage?.modelName
• Hook.afterAgent — output parameter widened string → unknown; typed hooks with explicit string signatures need updating
• HandlerConfig.sessionService — now optional; handlers auto-inherit the app's session service
• calculateCost(usage, modelName) → calculateCost(usage) — model name read from usage.modelName
• formatCost — sub-dollar amounts use toFixed instead of toPrecision
• RunStatus — 'inactivity-timeout' → 'inactivity_timeout', 'max-duration' → 'max_duration', 'participant-left' → 'participant_left'; added 'disconnected' and 'participant_left' as first-class statuses (previously collapsed to 'aborted')
• InvocationEndReason — same underscore renames as RunStatus; InvocationEndReason is now a strict subset of RunStatus
• InvocationState — limit end reasons (max_steps, max_turns, max_duration, inactivity_timeout, disconnected, participant_left) map to 'completed' instead of their raw reason string
• BaseRunner — sessionService constructor option is now optional (defaults to in-memory)
• computeResumeContext() — multi-turn resume no longer bails early when a prior turn's root invocation is terminal; the findYieldedNodes scan already handles "nothing to resume"

Deprecated

• AgentTimeouts.maxDuration — use expiry instead. Will be removed in 0.7.0.
• sessionService() factory — use adk({ store }) and app.sessions
• InMemoryStore, DynamoDBStore, PostgresStore, SQLiteStore classes — use inMemoryStore(), dynamoStore(), sqliteStore(), postgresStore()
• app.session() — use app.sessions.create()
• Standalone turn() — use app.handler.turn()

Removed

• ModelEndEvent.modelName — use ModelUsage.modelName
• gemini-2.5-flash high-tier pricing bracket (price changed)

2026-02-23

0.5.0

Eval API moves onto the app (app.evaluate, app.report), with full RunResult preserved per case and markdown report generation for persistent, agent readable, git-checkable records.

Added

• app.evaluate(cases, options) — runs eval cases (single or array) with tool mocking and metrics; returns EvalResult<T, S> with app state S and optional per-case context T
• app.report(result, options) — generates markdown from EvalResult; optional title, footer (string or function), sections, and renderCase for custom content
• EvalCaseResult.run — full RunResult (session, usage, output) preserved for reporting and metrics; convenience accessors .events, .usage, .turns
• EvalOptions.onCase — progress callback (result, index, total) => void called after each case completes
• EvalCase.retries — number of additional attempts for flaky cases; retries on failed, error, or timeout
• EvalCase.timeout — per-case timeout in ms; produces status: 'timeout' on expiry
• TestOptions.maxTurns — replaces maxIterations for consistency with SimulateOptions
• RunResult.state — typed TypedState<S> accessor (same type as result.session.state); symmetric with input: { state } on the input side
• AssistantEvent.media — optional MediaPart[] field; eliminates the need to cast when accessing media on assistant events
• Session.boundState(invocationId) — returns invocation-scoped TypedState; useful in custom context renderers
• Session.onStateChange(callback) — registers a state change observer
• Session.getSpawnedTaskStatus(id), Session.getRunningSpawnedTasks(), Session.getAllSpawnedTasks(), Session.waitForSpawnedTask(id), Session.waitForAllSpawnedTasks(), Session.hasRunningSpawnedTasks() — spawned task observation from hooks and tools
• VectorFilter nested filters — must, should, must_not arrays now accept nested VectorFilter objects for compound boolean logic (e.g. AND-within-OR for per-slice filtering)
• mem.slices(names) — subset accessor for searching, sampling, and filtering across a selected set of slices in one call; return type narrows to only the selected slice types
• SlicedSubset<TSlices> — type for the object returned by mem.slices()
• mem.variant.summary.returning('detailed') — cross-variant content: search using one variant's embeddings, return another variant's content

Changed

• Parser structured output — path-scoped visited key (no false circular ref); valid partial used on parse failure when it passes schema
• EvalCase — composes shared fields with SimulateOptions via Pick; initialState + firstMessage replaced by standard input (string or { message, state })
• EvalCaseResult — now EvalCaseResult<S> with run: RunResult<unknown, S>; tokenUsage → usage (type UsageSummary); events and turns preserved as convenience accessors
• Metric.evaluate — signature (events: Event[]) → (run: RunResult); events available as run.session.events; built-in metric factories updated
• Eval error shape — error on EvalCaseResult is now { message: string; stack?: string }; EvalError interface and phase field removed
• Eval status mapping — aborted run status now maps to EvalStatus: 'aborted' instead of falling through to pass/fail; metric name collisions between suite and case level emit a console warning
• app.handler.rest / app.handler.agui / app.handler.turn — now inherit app-level hooks and errorHandlers; handler-level config composes after app-level (app hooks run outer, handler hooks run inner)
• app.cli — now inherits app-level hooks, errorHandlers, and appName for session creation; CLI-level hooks compose after app-level; respects user-provided runner override
• Untyped state scopes return unknown instead of any — accessing properties on scopes without a schema (e.g. state.user.name when no user schema is defined) now requires explicit narrowing
• mem.variant renamed from mem.variants
• Memory internal key separator # → _ — vector names (model#variant → model_variant), metadata prefixes (_variant# → _variant_, _slice# → _slice_); existing collections must be re-indexed
• ModelStartEvent — messages: ContextMessageSummary[] → messageCount: number; serializedSchema removed. The CLI reconstructs exact context on-demand via session.forkAt() + buildContext() when the user expands a context block. Eliminates O(n²) storage of repeated context snapshots.
• SlicedMemory.slices → SlicedMemory.slice — singular accessor for per-slice operations (mem.slice.medication.search()); slices is now the subset method
• eventCountMetric / eventSequenceMetric — filter callback infers narrowed event type from eventType; casts no longer needed. Metric<S> threads the app's state schema through run.state

Internal

• Voice lifecycle state machine (idle → active → ending → ended) with atomic tryEnd() — first caller wins, concurrent shutdown events are safely ignored
• ADK-owned inactivity timer replaces LiveKit userAwayTimeout — supports repeated firings and inactivityCount reset on user speech

Removed

• Simulator type — removed from main package and adk/eval exports (was the literal signature of app.simulate)
• llmJudge / LlmJudgeConfig — removed from adk/eval; implement the Metric interface directly with your own judge agent (see migration below)
• runEval / runEvalSuite / EvalSuiteConfig — use app.evaluate(cases, options)
• EvalError — use error?: { message: string; stack?: string } on EvalCaseResult
• EvalCaseResult.tokenUsage — use result.usage (UsageSummary)
• EvalCase.initialState / EvalCase.firstMessage — use standard input (string or { message, state })
• TestOptions.maxIterations → TestOptions.maxTurns
• toolCallCountMetric — use eventCountMetric with eventType: 'tool_call' and a filter
• durationMetric — use timingMetric with measure: 'total_duration'
• modelLatencyMetric — use timingMetric with measure: 'model_latency_average'
• timeToFirstResponseMetric — use timingMetric with measure: 'time_to_first_assistant'

Migration from 0.4.x

EvalCase: initialState / firstMessage → input

EvalCase now uses the standard input field (same as app.run and app.simulate) instead of separate initialState and firstMessage fields.

```typescript

// Before

{ initialState: { session: { orgId: 'org-1' } }, firstMessage: 'Hello' }

// After

{ input: { message: 'Hello', state: { orgId: 'org-1' } } }

// or just: { input: 'Hello' }

```

Custom metrics: (events) → (run)

Metrics receive the full run; events are on run.session.events.

```typescript

// Before

const metric = {

name: 'my_metric',

evaluate: (events: Event[]) => {

/* ... */

},

}

// After

const metric = {

name: 'my_metric',

evaluate: (run: RunResult) => {

const events = [...run.session.events]

// ... same logic, or use run.usage, run.output, run.session.state

},

}

```

llmJudge → custom Metric

llmJudge assumed a fixed transcript format and generic pass/fail schema. Implement Metric directly with your judge agent; the metric now receives RunResult so you can pass session or output into the judge.

```typescript

// Before

import { llmJudge } from '@animahealth/adk/eval'

const metric = llmJudge({

name: 'quality',

prompt: '...',

model: openai('gpt-5-mini'),

passingScore: 0.8,

})

// After

import type { Metric, MetricResult } from '@animahealth/adk/eval'

return {

name: 'quality',

evaluate: async (run): Promise<MetricResult> => {

// build input from run.session.events or run.output, then run judge agent

const { output } = await app.run(judgeAgent, { input: judgeInput })

return {

passed: output.value!.score >= 0.8,

score: output.value!.score,

evidence: [output.value!.reasoning],

}

},

}

```

2026-02-20

0.4.6

Added

• handler.turn — shared streaming lifecycle (resolve session, run, stream events, commit, resolve conflict); returns StreamResult<TurnResult> with invocationId on the stream; use for custom projections (Slack, cron, CLI) without duplicating persistence
• Hook.afterTurn — turn-level lifecycle hook that runs within the handler.turn commit boundary (after run completes, before commitSession); state mutations are included in the commit atomically; receives TurnContext with session, result, and runnable
• TurnContext — context type for afterTurn; provides writable session, RunResult, and the runnable
• CommitStatus, TurnResult — TurnResult extends RunResult with sessionId, invocationId, optional commitStatus ('committed' | 'merged' | 'skipped' | 'orphaned')
• RunConfig.invocationId — optional root invocation ID; when set, runner uses it instead of generating one (enables traceability with AG-UI runId)
• RunConfig.errorHandlers — per-run error handlers, composed after runner and agent handlers (mirrors RunConfig.hooks)
• sqliteIndex() — SQLite vector index provider via sqlite-vec with auto-provisioning
• voyage() sagemaker option — SageMaker endpoint with automatic fallback to Voyage API; each path retries independently
• VectorCondition.range — string bounds for datetime range filtering across all providers
• VectorCondition.text — case-insensitive text matching on string metadata fields; contains accepts string | string[] (array = OR)
• SearchOptions.contains — shorthand for text matching against stored content
• CollectionSpec.textIndexes — payload field names that need a text index for content search (Qdrant)
• normalizeFilter() — filter shorthand: { org: 'acme' } expands to { must: [{ key: 'org', match: { value: 'acme' } }] }; all filter-accepting methods (search, context, tool, sample, scroll, count) accept the shorthand via FilterInput
• slices config on memory() — heterogeneous collections with per-slice typed metadata; records.slices.medication.search() returns SearchResult<MedicationMeta>, records.search() returns a discriminated union with match.kind for narrowing (renamed to records.slice in 0.5.0)
• SlicedMemory, SliceAccessor, SlicedMatchUnion, SlicedSearchResult — types for sliced memory
• CollectionSpec.payloadIndexes — auto-populated with _slice#kind when slices are declared
• Match.kind — optional; present when the document belongs to a slice
• better-sqlite3, sqlite-vec, @aws-sdk/client-sagemaker-runtime — optional peer dependencies

Changed

• handler.agui — delegates to turn; events stream live (no buffering until commit); AG-UI runId is the turn’s invocationId; RUN_FINISHED result payload includes commitStatus for reconciliation
• handler.rest — delegates to turn internally; external contract (buffered JSON response) unchanged
• resolveConflict return type — ConflictOutcome → CommitStatus (same values, adds 'committed' for happy path)
• UpsertItem.content — now required; content is stored alongside vectors and returned as Match.content
• Upsert metadata — merge semantics across variants instead of replace
• CollectionSpec.textIndexes — Qdrant users should provision text indexes from this field to enable SearchOptions.contains
• VoyageModel.dimensions — now required; voyage('voyage-4') → voyage('voyage-4', { dimensions: 1024 })
• MemoryConfig.variant → MemoryConfig.variants — singular string replaced by string array; omit for implicit ['default']
• mem.variant('name') → mem.variants.name (changed to variant in 0.5.0) — dynamic method replaced by upfront property map
• collectionSpec(config, variants) → collectionSpec(config) — variants now read from config.variants
• Internal metadata prefix _content# → _variant#; _slice# reserved for slices

Removed

• createRunId() — use turn(config, input).invocationId (or the root invocation ID from the stream) as AG-UI runId
• ConflictOutcome — replaced by CommitStatus (import from handler or runtime types)
• vectorKey() — no longer public; use collectionSpec() instead
• EmbedResult, Point, VectorMatch, DistanceMatrixPair, DistanceMatrixResult — removed from top-level exports (importable from @animahealth/adk/memory for custom providers)
• MemoryContextConfig, MemoryToolConfig — removed aliases; use inline mem.context() / mem.tool() config

Migration from 0.4.5

Memory variant API

```typescript

// Before

const mem = memory({ ..., variant: 'questionnaire' });

const full = mem.variant('full');

// After

const mem = memory({ ..., variants: ['questionnaire', 'full'] });

const full = mem.variants.full; // (changed to variant in 0.5.0)

```

Memory collectionSpec signature

```typescript

// Before

collectionSpec({ model, collection }, ['questionnaire', 'full'])

// After

collectionSpec({ model, collection, variants: ['questionnaire', 'full'] })

```

2026-02-15

0.4.5

Added

• memory() — composable vector memory; typed metadata via Zod schema, provider-agnostic Embedder / VectorIndex interfaces
• voyage() — Voyage AI embedding provider with batching (128/request), automatic inputType routing, retry
• qdrant() — Qdrant vector index provider with retry
• pgvector() — pgvector vector index provider (PostgreSQL) with auto-provisioning, HNSW indexing, retry
• inMemoryIndex() — in-memory vector index with real cosine similarity for testing and prototyping
• mem.context() — returns ContextRenderer for deterministic recall before reasoning
• mem.tool() — returns FunctionTool for agent-driven recall via tool call
• mem.search() — returns typed Match<TMetadata>[] and computed embedding for downstream forwarding
• mem.upsert() — batch-aware write accepting content (embeds) or pre-computed embedding; validates dimensions
• mem.updateMetadata() — merge metadata without re-embedding; null deletes keys
• mem.variant() — named vector variants sharing collection, schema, and providers
• mem.sample() — representative sampling via density-weighted farthest-point selection; optional query-focused mode with gravity
• vectorKey() — exported so provisioning scripts, Terraform generators, and migration jobs can compute the same model#variant vector names the ADK uses internally
• collectionSpec() — computes collection vector specifications from memory config for provisioning
• representativeSample(), estimateDensity() — exported sampling utilities for custom workflows
• Embedder, EmbedResult, VectorIndex, Match, Point — exported types for custom provider implementations
• voyageai, @qdrant/js-client-rest, pg — optional peer dependencies

2026-02-11

0.4.4

Added

• Event type guards — isToolCallEvent, isToolYieldEvent, isToolInputEvent, isToolResultEvent, isAssistantEvent, and 10 more for every Event/StreamEvent member
• SimulateYieldContext exported from main entry point

Changed

• SimulateYieldContext, Transform, SimulateOptions — now generic over TArgs (defaults to unknown) so Transform callbacks can type ctx.args without casting

2026-02-11

0.4.3

Changed

• Eval, run, test, simulate, CLI, and handlers — Runnable/Hook at orchestration boundaries widened to Runnable<any> / Hook<any>[] so typed agents and hooks work without casts

2026-02-10

0.4.2

Exports the eval framework as @animahealth/adk/eval and moves simulation termination into the core run loop.

Added

• @animahealth/adk/eval — subpath export: runEval, runEvalSuite, interceptTools, metric factories, types
• SimulateOptions.maxTurns, .maxDuration, .stateMatches — flat termination fields replacing maxIterations
• RunStatus: 'terminated' with terminationReason: TerminationReason on the result
• SimulateOptions.userAgent is now optional — tool-only flows no longer need a stub

Changed

• SimulateOptions.maxIterations → maxTurns
• EvalSuiteConfig.parallel: boolean → concurrency: number (defaults to Infinity; use 1 for sequential)
• runEval / runEvalSuite — first arg is now a Simulator function (pass app.simulate)

Removed

• SimulateOptions.maxIterations — use maxTurns
• EvalSuiteConfig.parallel — use concurrency

Migration from 0.4.1

Max-iterations status change

maxIterations exceeded previously returned status: 'error'. It now returns status: 'terminated' with terminationReason: 'maxTurns'. Code that checked result.status === 'error' for iteration limits must check 'terminated' instead.

2026-02-09

0.4.1

Added

• app.hook() — callable hook namespace for typed custom hooks, mirroring app.context()
• createEventId / createCallId — exported from public API

Changed

• ToolYieldEvent.preparedArgs → ToolYieldEvent.args
• yieldedTools — returns ToolYieldEvent[] instead of ToolCallEvent[]
• CLI — pending yields show enriched tool_yield args instead of raw tool_call args
• OpenAI — synthetic call IDs normalized to fc_ prefix at serialization boundary

Migration from 0.4.0

yieldedTools returns ToolYieldEvent[] instead of ToolCallEvent[]

session.yieldedTools, RunResult.yieldedTools, and RestResponse.yieldedTools now return the enriched ToolYieldEvent (with prepare args) instead of the raw ToolCallEvent. Code that accessed yieldedTools[n].args continues to work — the args are now the enriched version from prepare.

2026-02-09

0.4.0

Consolidates the public API with a canonical Input/Output pair — descriptive yield statuses, unified media and tool, namespaced handler payloads, fewer redundant types.

Changed

• RenderContext — all fields are now readonly; context renderers must return new objects instead of mutating
• RunResult.status — 'yielded' → 'yielded_tool', 'input_required' → 'yielded_message'; each branch of the discriminated union carries only its relevant fields
• app.run() / app.test() / app.simulate() / ctx.call() (renamed to ctx.run() in 0.5.1) / ctx.spawn() — typed Agent<TOutput> overloads that preserve output type through to the result
• ImageSource / AudioSource / DocumentSource → MediaSource; MessageInput.images / .audio → media: MediaPart[]
• ToolInput / ResultInput → ToolInput { callId, input }; session.input.tool() now handles both tool yields and tool call results
• TestOptions — messages → userHandler, tools → toolHandlers; SimulateOptions / EvalCase — simulator → userAgent, tools → toolAgents
• Hook | Hook[] → Hook[] — hooks options now only accept an array; wrap a single hook in [hook]
• CallOptions / SpawnOptions / DispatchOptions → HandoffOptions
• FunctionToolHookContext → ToolExecutionContext
• RunResultOutput<T> → Output<T> — canonical output shape shared by RunResult, Session, CallResult (renamed to SubRunResult in 0.5.1), SpawnResult
• RunInput / BaseInput → Input — canonical input shape with message, tools, and state fields
• HandlerInput, RunOptions, TestOptions, SimulateOptions — payload fields grouped under input namespace; HandlerInput.input uses Input directly; toolInputs → input.tools; message widened to string | MessageInput
• RestResponse.output — uses canonical Output type; opt-in events, usage via HandlerConfig.response
• RestResponse.yieldedTools — yielded tools promoted to top-level field (replaces toolCall / toolCalls)
• session.pendingYieldingCalls → session.yieldedTools; result.pendingCalls → result.yieldedTools; pendingCallIds → yieldedToolIds

Removed

• result.response — use result.output.value or result.output.text
• result.awaitingInput — check result.status === 'yielded_message'
• ImageSource, AudioSource, DocumentSource, ImageInput, AudioInput — use MediaSource / MediaPart[]
• ResultInput, session.input.result() — use ToolInput / session.input.tool()
• CallResultOutput, CallOptions, SpawnOptions, DispatchOptions, FunctionToolHookContext, ToolHookContext
• RunResultOutput — use Output
• RunInput, BaseInput — use Input
• SessionOutputNamespace — session.output now returns Output directly
• AdkRunConfig — use RunOptions

Migration from 0.3.x

Immutable RenderContext

```typescript

// Before

app.context((ctx) => {

ctx.events.push(systemEvent)

ctx.allowedTools = ['search']

return ctx

})

// After

app.context((ctx) => ({

...ctx,

events: [...ctx.events, systemEvent],

allowedTools: ['search'],

}))

```

Yield statuses

```typescript

// Before

if (result.status === 'yielded') {

if (result.awaitingInput) {

/* loop */

} else {

/* tool */

}

}

// After

if (result.status === 'yielded_tool') {

session.input.tool({ callId: result.yieldedTools[0].callId, input: data })

}

if (result.status === 'yielded_message') {

session.input.message({ text, invocationId: result.yieldedInvocationId })

}

```

Tool input

```typescript

// Before

session.input.tool({ callId, data: value })

// After

session.input.tool({ callId, input: value })

```

Media input

```typescript

// Before

session.input.message({ text, images: [{ url }], audio: [{ mimeType, data }] })

// After

session.input.message({

text,

media: [

{ type: 'image', source: { type: 'url', url } },

{ type: 'audio', source: { type: 'base64', mimeType, data } },

],

})

```

Orchestration options

```typescript

// Before (ctx.call renamed to ctx.run in 0.5.1)

ctx.call(agent, { message: 'hello', tempState: { key: 'val' } })

// After (ctx.call renamed to ctx.run in 0.5.1)

ctx.call(agent, { input: { message: 'hello', state: { key: 'val' } } })

```

Input / Output types

```typescript

// Before

import type { RunInput, BaseInput, RunResultOutput } from '@animahealth/adk'

const input: RunInput = { message: 'Hello' }

const output: RunResultOutput = result.output

// After

import type { Input, Output } from '@animahealth/adk'

const input: Input = { message: 'Hello' }

const output: Output = result.output

```

Handler Input

```typescript

// Before

handler({ sessionId: 'abc', message: 'Hello', state: { mode: 'debug' } })

handler({

sessionId: 'abc',

toolInputs: [{ callId: 'c1', data: { ok: true } }],

})

// After

handler({

sessionId: 'abc',

input: { message: 'Hello', state: { mode: 'debug' } },

})

handler({

sessionId: 'abc',

input: { tools: [{ callId: 'c1', input: { ok: true } }] },

})

```

Handler Output

```typescript

// Before

response.output // string

response.toolCall // { callId, name, args }

response.toolCalls // Array<{ callId, name, args }>

// After

response.output.text // string

response.yieldedTools // Array<{ callId, name, args }>

```

RunOptions / TestOptions

```typescript

// Before

app.run(agent, { input: 'Hello', state: { mode: 'debug' } })

app.test(agent, { input: 'Start', tools: { ask: [{ answer: 'Blue' }] } })

// After

app.run(agent, { input: { message: 'Hello', state: { mode: 'debug' } } })

app.test(agent, {

input: { message: 'Start', tools: { ask: [{ answer: 'Blue' }] } },

})

```

app.run(agent, 'Hello') string shorthand is unchanged.

Yield Renames

```typescript

// Before

session.pendingYieldingCalls

result.pendingCalls

event.pendingCallIds

// After

session.yieldedTools

result.yieldedTools

event.yieldedToolIds

```

2026-02-07

0.3.1

Fixed

• Yielding tool safeParse failure — feed validation errors back as tool_result instead of silently hanging
• Consistent ID prefixes for forked sessions (session_) and AG-UI runs (run_)

2026-02-07

0.3.0