feat(js): implemented defineAgent

[pavelgj]

Introduces defineAgent and friends: a first-class, multi-turn agent API for Genkit JS. An agent bundles a model/prompt, conversational state, tool loops, interrupts, persistence, streaming, and abort/resume into a single ergonomic, transport-agnostic surface that runs identically in-process on the server and over HTTP from a browser.

Highlights

• Three ways to define an agent, from zero-config to full control.
• Stateful, multi-turn chats that thread snapshotId/state for you.
• Typed custom state with Zod validation (stateSchema).
• Pluggable persistence via SessionStore (in-memory + file stores included), with server-managed sessions resumable by sessionId.
• Streaming with live custom-state patches over the wire (JSON Patch).
• Interrupts & resume (restart / respond) for human-in-the-loop tools.
• Abort, detach (background turns) + heartbeats, and graceful failure with last-good state.
• clientTransform to redact/reshape state and stream chunks before they leave the server.
• Transport-agnostic: the same AgentAPI is returned by ai.defineAgent(...) on the server and remoteAgent(...) on the client.

---

1. Define an agent

The headline API — one call wires up a prompt and a multi-turn agent:

constagent=ai.defineAgent({name: 'assistant',model: 'googleai/gemini-flash-latest',system: 'You are a helpful assistant.',tools: [searchTool],});

Prompt-driven (reuse a registered .prompt), with typed promptInput:

constagent=ai.definePromptAgent({promptName: 'assistant',promptInput: {role: 'pirate',tone: 'cheerful'},// type-checked vs prompt's input schema});

Full control via a custom turn handler:

constagent=ai.defineCustomAgent({name: 'custom'},async(runner,input)=>{// own the turn: call models, tools, mutate session state, return a result});

2. Chat: send & stream

chat() returns a stateful conversation that tracks state, messages, snapshotId, and sessionId so you don't thread them by hand:

constchat=agent.chat();constres=awaitchat.send('Hello!');console.log(res.text,res.finishReason);// 'Hi! ...', 'stop'// streamingconstturn=chat.sendStream('Write a poem');forawait(constchunkofturn.stream){process.stdout.write(chunk.text??'');}constfinal=awaitturn.response;

3. Typed custom state

constagent=ai.defineAgent({name: 'cart',model: 'googleai/gemini-flash-latest',stateSchema: z.object({items: z.array(z.string())}),});constchat=agent.chat({state: {items: []}});awaitchat.send('add milk');console.log(chat.state);// { items: ['milk'] } (validated against stateSchema)

4. Persistence & resuming sessions

Attach a SessionStore to make an agent server-managed: turns are persisted as snapshots and a chat can be resumed later by sessionId (no need to track snapshot IDs) or by an exact snapshotId:

import{FileSessionStore}from'@genkit-ai/ai/session-stores';constagent=ai.defineAgent({name: 'assistant',model: 'googleai/gemini-flash-latest',store: newFileSessionStore('./sessions'),});constchat=agent.chat();awaitchat.send('Remember my name is Ada.');const{ sessionId }=chat;// later, somewhere else:constresumed=awaitagent.loadChat({ sessionId });awaitresumed.send('What is my name?');// -> "Ada"

Built-in stores: InMemorySessionStore and FileSessionStore (with filesystem snapshot watching + configurable poll fallback). The SessionStore interface uses an atomic mutator-based saveSnapshot to make concurrent writes (e.g. an abort racing a completion) safe.

5. Interrupts & resume (human-in-the-loop)

When a tool interrupts, the turn finishes with finishReason: 'interrupted'. Resume by either re-running the tool (restart) or supplying the answer directly (respond):

letres=awaitchat.send('Transfer $100 to Bob');if(res.finishReason==='interrupted'){res=awaitchat.resume({respond: [confirmTransfer.respond(res,{approved: true})],});}

6. Abort, detach & graceful failure

// abort an in-flight turnconstturn=chat.sendStream('long task...');awaitchat.abort();// background / detached turns with heartbeat-based livenessconsttask=awaitchat.detach('run this in the background');forawait(conststatusoftask.watch()){/* pending -> completed/expired */}

Failures resolve gracefully (finishReason: 'failed') and preserve the last-good snapshot/state instead of corrupting the session; genuine API misuse throws AgentInitError.

7. Redact / reshape state for clients

constagent=ai.defineAgent({name: 'assistant',model: 'googleai/gemini-flash-latest',clientTransform: {state: (s)=>({ ...s,secret: undefined}),// redact at rest / in responseschunk: (c)=>c,// reshape or drop stream chunks in flight},});

8. Same API, server or browser

The server returns an AgentAPI; the client gets the exact same shape from remoteAgent(...), so UI code is identical whether it runs in-process or over HTTP:

import{remoteAgent}from'genkit/beta/client';constagent=remoteAgent({url: 'https://my-app/agents/assistant'});constchat=agent.chat();constturn=chat.sendStream('Hello from the browser');forawait(constchunkofturn.stream){render(chunk);}

---

What's inside

• js/ai/src/agent.ts — defineAgent / definePromptAgent / defineCustomAgent, schemas, session runner, finish reasons, error handling.
• js/ai/src/agent-core.ts — transport-agnostic AgentAPI / AgentChat / AgentResponse, in-process transport, custom-state patching.
• js/ai/src/session.ts, js/ai/src/session-stores.ts — Session, SessionStore, InMemorySessionStore, FileSessionStore, snapshot model + heartbeats.
• js/ai/src/json-patch.ts — minimal, pollution-safe JSON Patch used for streaming custom-state updates.
• js/genkit/src/client/* — remoteAgent HTTP client.
• js/genkit/src/beta.ts / genkit-beta.ts — ai.defineAgent etc. + ai.currentSession() exposed on the beta surface.
• Extensive tests: agent_test.ts, agent_client_test.ts, session-stores_test.ts, json-patch_test.ts.

Finish reasons:stop, interrupted, failed, aborted, blocked, detached, unknown.
Snapshot statuses:pending, completed, failed, aborted, expired.