Serve agents over HTTP

Beta

The Agents API is in Beta. It can introduce breaking changes in minor version releases.

HTTP serving lets browser apps, mobile apps, other services, and agents written in another language use the same conversational runtime. The wire protocol has a primary turn endpoint and optional companion endpoints for snapshots and aborts. Over it, a client streams model output, custom state, artifacts, and interrupts through one agent interface, then continues the next turn with a session ID, snapshot ID, or client-managed state.

Express routes

Every Genkit agent is a bidirectional action. Serve the agent action itself for turns. Serve the snapshot companion only for server-managed agents, and serve the abort companion only when clients need to cancel detached work.

import { expressHandler } from '@genkit-ai/express';
import express from 'express';

const app = express();

app.post('/api/weatherAgent', expressHandler(weatherAgent));

app.post(
  '/api/weatherAgent/getSnapshot',
  expressHandler(weatherAgent.getSnapshotDataAction),
);

app.post(
  '/api/weatherAgent/abort',
  expressHandler(weatherAgent.abortAgentAction),
);

app.listen(8080);

The primary endpoint handles normal and streaming turns. The snapshot endpoint reads by snapshotId or sessionId. The abort endpoint takes { snapshotId }.

Route layout

Agent routes follow a consistent layout across backend frameworks:

• POST /agents/{name} (or /api/{name}): Always exists. It handles one turn per request. Add ?stream=true for server-sent events.
• POST /agents/{name}/getSnapshot (or /api/{name}/getSnapshot): Exists when the agent has a session store. Use it to read by snapshotId or by latest sessionId.
• POST /agents/{name}/abort (or /api/{name}/abort): Exists when the agent has a store that supports status subscriptions. Use it to cancel detached background work.

Every route uses the standard Genkit HTTP envelope. The turn input goes in data, and session initialization goes in the optional init. Omit init to start a fresh conversation, or include sessionId, snapshotId, or state to continue one.

curl -X POST http://localhost:8080/agents/chat \
  -H 'content-type: application/json' \
  -d '{"data":{"message":{"role":"user","content":[{"text":"Weather in Tokyo?"}]}}}'

Response envelope

A non-streaming turn answers with the reflection API’s result envelope wrapping one AgentOutput:

{
  "result": {
    "message": {
      "role": "model",
      "content": [{ "text": "Tokyo is 18°C and clear." }]
    },
    "sessionId": "6b1c2f3e-6a1e-4c1b-9c74-1f2b8d0a5e11",
    "snapshotId": "9f2a41d6-0c2b-4f0e-8a7a-3f9d1c6b2e40",
    "finishReason": "stop"
  }
}

The fields of AgentOutput:

Field	Meaning
message	The last model response message of the conversation.
sessionId	The conversation’s ID. The framework assigns it on the first invocation and it is stable across resumes.
snapshotId	The most recent turn-end snapshot. Present only when the agent has a session store.
state	The full SessionState. Present only for client-managed agents, those with no store.
artifacts	Artifacts produced during the session.
finishReason	Why the invocation finished: stop, length, blocked, interrupted, other, unknown, aborted, detached, or failed.
error	Structured failure details. Present only when finishReason is failed.

Copy result.sessionId into init.sessionId on the next request, and result.snapshotId into the getSnapshot and abort bodies. When streaming, read the session ID from the terminal data: {"result": ...} frame; chunk frames do not carry it. For a client-managed agent it also rides at result.state.sessionId.

Continue a server-managed conversation with the ID the previous response returned:

curl -X POST http://localhost:8080/agents/chat \
  -H 'content-type: application/json' \
  -d '{"data":{"message":{"role":"user","content":[{"text":"What about Paris?"}]}},"init":{"sessionId":"6b1c2f3e-6a1e-4c1b-9c74-1f2b8d0a5e11"}}'

Continue a client-managed conversation by sending back the state object from the previous response. An agent defined without a session store returns responses that carry the whole SessionState: sessionId, messages, custom, and artifacts.

curl -X POST http://localhost:8080/agents/statelessChat \
  -H 'content-type: application/json' \
  -d '{"data":{"message":{"role":"user","content":[{"text":"What is my name?"}]}},"init":{"state":{"sessionId":"6b1c2f3e-6a1e-4c1b-9c74-1f2b8d0a5e11","messages":[{"role":"user","content":[{"text":"My name is Alex."}]},{"role":"model","content":[{"text":"Nice to meet you, Alex."}]}],"custom":{}}}}'

Streaming

Stream a turn as server-sent events:

curl -N -X POST 'http://localhost:8080/agents/chat?stream=true' \
  -H 'content-type: application/json' \
  -d '{"data":{"message":{"role":"user","content":[{"text":"Suggest three day trips from Tokyo."}]}},"init":{}}'

Sending Accept: text/event-stream turns streaming on as well, with or without ?stream=true.

Every frame is one data: line. There are three shapes:

data: {"message":{"modelChunk":{"role":"model","content":[{"text":"Nikko"}]}}}

data: {"message":{"modelChunk":{"role":"model","content":[{"text":" is a good day trip."}]}}}

data: {"message":{"turnEnd":{"finishReason":"stop","snapshotId":"9f2a41d6-0c2b-4f0e-8a7a-3f9d1c6b2e40"}}}

data: {"result":{"message":{"role":"model","content":[{"text":"Nikko is a good day trip."}]},"sessionId":"6b1c2f3e-6a1e-4c1b-9c74-1f2b8d0a5e11","snapshotId":"9f2a41d6-0c2b-4f0e-8a7a-3f9d1c6b2e40","finishReason":"stop"}}

• {"message": <chunk>} repeats for each streamed chunk. The inner object represents the stream chunk, carrying fields such as modelChunk, customPatch, artifact, and turnEnd.
• {"result": <AgentOutput>} is the terminal frame and the only one that carries sessionId.
• {"error": {"status": ..., "message": ...}} replaces the terminal frame when the stream fails.

Reading custom state from a raw client

Custom state reaches a raw HTTP client as customPatch on a chunk, an RFC 6902 JSON Patch rooted at the custom document. Its pointers have no /custom prefix, so a field named agentStatus is at /agentStatus:

data: {"message":{"customPatch":[{"op":"replace","path":"","value":{"agentStatus":"searching"}}]}}

data: {"message":{"customPatch":[{"op":"replace","path":"/agentStatus","value":"summarizing"}]}}

The first patch of each turn is a whole-document replace at the root pointer "", which re-bases a client that joined mid-conversation. Apply later patches incrementally to keep a local copy live. In Go, use aix.ApplyPatch; browser clients can use standard RFC 6902 libraries like fast-json-patch. The Vercel AI SDK transport described below performs this reassembly automatically.

Interrupts over HTTP

When an interruptible tool pauses, the turn returns HTTP 200: finishReason is interrupted and the interrupt rides as a tool-request part on the message content, carrying the tool’s payload under metadata.interrupt.

{
  "result": {
    "finishReason": "interrupted",
    "message": {
      "role": "model",
      "content": [
        {
          "toolRequest": {
            "name": "transferMoney",
            "ref": "call_1",
            "input": { "toAccount": "alice", "amount": 200 }
          },
          "metadata": {
            "interrupt": { "reason": "large_amount", "amount": 200 }
          }
        }
      ]
    },
    "sessionId": "6b1c2f3e-6a1e-4c1b-9c74-1f2b8d0a5e11",
    "snapshotId": "9f2a41d6-0c2b-4f0e-8a7a-3f9d1c6b2e40"
  }
}

Answer it on the next request through data.resume, which takes respond, restart, or both:

curl -X POST http://localhost:8080/agents/banker \
  -H 'content-type: application/json' \
  -d '{"data":{"resume":{"restart":[{"toolRequest":{"name":"transferMoney","ref":"call_1","input":{"toAccount":"alice","amount":200}},"metadata":{"resumed":{"approved":true}}}]}},"init":{"sessionId":"6b1c2f3e-6a1e-4c1b-9c74-1f2b8d0a5e11"}}'

respond supplies the tool’s output directly; restart re-runs the tool with a typed answer. The runtime validates the payload: name and ref must match a pending tool request in the most recent model response, and a restarted request must carry its original input unmodified. See Agent interrupts.

Snapshot and abort companions

Read a snapshot:

curl -X POST http://localhost:8080/agents/chat/getSnapshot \
  -H 'content-type: application/json' \
  -d '{"data":{"snapshotId":"9f2a41d6-0c2b-4f0e-8a7a-3f9d1c6b2e40"}}'

Abort detached work:

curl -X POST http://localhost:8080/agents/chat/abort \
  -H 'content-type: application/json' \
  -d '{"data":{"snapshotId":"9f2a41d6-0c2b-4f0e-8a7a-3f9d1c6b2e40"}}'

Both take the snapshotId a previous turn returned at result.snapshotId. See Background execution.

Failure tiers

Failures arrive at two different levels:

• Turn-level failures: A failed turn returns 200 with finishReason: "failed" along with structured error details and the last known good state, allowing the client to retry or handle the failure without losing conversation state.
• Request-level failures: A malformed init payload (such as an unknown snapshotId or sending state to a store-backed agent) fails immediately with an HTTP 4xx error before running the turn.

Session ID handling

If a store-backed agent receives a sessionId that does not exist in the store, it initializes a new conversation under that ID. If your application needs to restrict client-generated session IDs, validate the identifier in your authentication or authorization middleware before invoking the agent handler.

Connect a client

The client is independent of the backend language. Point it at the primary turn URL your server exposes, the route you mounted above, and it speaks the same wire protocol either way. The snapshot and abort companion URLs follow your server’s route layout.

The snippets below apply whichever backend language you selected.

remoteAgent() from the genkit npm package (npm i genkit) creates a browser-safe client with the same AgentAPI shape as a local agent.

import { remoteAgent } from 'genkit/beta/client';

const agent = remoteAgent<WeatherState>({
  url: 'http://localhost:8080/api/weatherAgent',
});

const chat = agent.chat();
const res = await chat.send('Weather in Tokyo?');

console.log(res.text);

Options:

• url is required and sends normal and streaming turns.
• getSnapshotUrl defaults to ${url}/getSnapshot and loads saved snapshots for server-managed agents.
• abortUrl defaults to ${url}/abort and cancels detached background turns.
• headers can be a static object or an async function called for each request. Use the function form when tokens rotate or are fetched from the current frontend session.
• stateManagement explicitly declares server or client state. The client otherwise infers the mode from responses.

Stream a turn

sendStream() returns a turn that exposes a chunk stream and a final response.

const turn = agent.chat().sendStream('Write a long report.');

for await (const chunk of turn.stream) {
  if (chunk.text) process.stdout.write(chunk.text);
  if (chunk.custom) updateStatus(chunk.custom);
}

const res = await turn.response;

Client behavior

The remote client calls the primary endpoint with streamed action transport. It resolves dynamic headers per request, supports foreground aborts, applies streamed custom-state patches, and throws AgentError for failed turns.

When using server-managed state, make sure the same auth and tenant checks apply to the primary, snapshot, and abort endpoints. Snapshot IDs are powerful because they can reveal conversation history. Treat them like conversation-scoped credentials, and verify that the caller is allowed to read or abort the requested session.

For client-managed agents, the remote client sends the full state back to the primary endpoint. That keeps the server stateless, but request size grows with conversation history and artifacts. Prefer server-managed routes for long-running chat experiences or background tasks.

Vercel AI SDK UI and AI Elements

@genkit-ai/vercel-ai connects an agent to the Vercel AI SDK UI library — the framework chat bindings such as useChat, not the broader Vercel AI SDK. GenkitChatTransport implements AI SDK UI’s framework-agnostic ChatTransport, so it works with any of the bindings, including React, Vue, Svelte, and Angular. The transport speaks the same wire protocol over the agent route, so a JavaScript frontend can call a Genkit agent HTTP backend in any supported language.

With the agent behind an AI SDK UI binding, you drive it from the SDK’s chat primitives instead of wiring up remoteAgent() yourself. In React, you can also assemble the interface from Vercel’s AI Elements components, which are built on the AI SDK UI primitives.

This path is server-managed only. The transport sends the chat id to the agent as its sessionId, and the agent persists each turn in its session store, so there is no client-side snapshot bookkeeping. The id must be a bare UUID.

Install it alongside the AI SDK UI binding you use:

npm i @genkit-ai/vercel-ai

Point the transport at the same agent route you serve for turns. The examples below use /api/weatherAgent; replace it with the path your own server mounts, shown in the routing section above. A same-origin path works when the frontend is served from the backend process or proxied to it. A cross-origin URL such as http://localhost:8080/agents/weatherAgent needs CORS headers on the agent route.

These examples use React and Angular; the Vue and Svelte bindings accept the same GenkitChatTransport.

React

import { useMemo, useState } from 'react';
import { useChat } from '@ai-sdk/react';
import { GenkitChatTransport } from '@genkit-ai/vercel-ai/client';

function Chat() {
  // The chat id is sent to the agent as its sessionId, so it must be a UUID.
  const chatId = useMemo(() => crypto.randomUUID(), []);
  const [input, setInput] = useState('');

  const { messages, sendMessage, status } = useChat({
    id: chatId,
    transport: new GenkitChatTransport({ url: '/api/weatherAgent' }),
  });

  return (
    <>
      {messages.map((message) => (
        <div key={message.id}>
          <strong>{message.role}: </strong>
          {/* A UIMessage is a list of typed parts; render the text ones. */}
          {message.parts.map((part, i) =>
            part.type === 'text' ? <span key={i}>{part.text}</span> : null,
          )}
        </div>
      ))}

      <form
        onSubmit={(e) => {
          e.preventDefault();
          if (!input.trim()) return;
          sendMessage({ text: input });
          setInput('');
        }}
      >
        <input value={input} onChange={(e) => setInput(e.target.value)} />
        <button disabled={status !== 'ready'}>Send</button>
      </form>
    </>
  );
}

Angular

import { Component, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { Chat } from '@ai-sdk/angular';
import { GenkitChatTransport } from '@genkit-ai/vercel-ai/client';

@Component({
  selector: 'app-chat',
  imports: [FormsModule],
  template: `
    @for (message of chat.messages; track message.id) {
      <div>
        <strong>{{ message.role }}: </strong>
        <!-- A UIMessage is a list of typed parts; render the text ones. -->
        @for (part of message.parts; track $index) {
          @if (part.type === 'text') {
            <span>{{ part.text }}</span>
          }
        }
      </div>
    }

    <form (submit)="$event.preventDefault(); send()">
      <input
        [ngModel]="input()"
        (ngModelChange)="input.set($event)"
        name="input"
      />
      <button [disabled]="chat.status !== 'ready'">Send</button>
    </form>
  `,
})
export class ChatComponent {
  input = signal('');

  // The chat id is sent to the agent as its sessionId, so it must be a UUID.
  // `Chat` is signal-backed, so `chat.messages` and `chat.status` are reactive
  // in the template.
  chat = new Chat({
    id: crypto.randomUUID(),
    transport: new GenkitChatTransport({ url: '/api/weatherAgent' }),
  });

  send() {
    if (!this.input().trim()) return;
    this.chat.sendMessage({ text: this.input() });
    this.input.set('');
  }
}

Neither binding manages input state, so you hold it yourself and pass the text to sendMessage({ text }). Each message is a UIMessage whose parts array holds typed segments (text, tool calls, and so on); the loop above renders the text parts. status is ready when the agent is idle.

Reading custom state and tool calls

AI SDK UI streams structured data alongside the chat as data parts, delivered through the binding’s onData callback rather than added to messages. This is the SDK’s standard channel for anything that is not chat text, and the transport reuses it to carry the agent’s custom state: each time the agent updates its session state, it emits a transient data-custom part with the full, current state. Because it is transient and never lands on a message, a UI that only renders messages never sees it — read it in onData. Both useChat(options) and new Chat(options) take onData in the same options object as id and transport:

onData: (part) => {
  if (part.type === 'data-custom') {
    // part.data is the agent's full, current custom state.
    renderCustomState(part.data);
  }
},

Tool calls arrive as tool-<name> parts on the assistant message, each advancing through a state lifecycle: input-streaming → input-available → output-available (or output-error). Scan the latest assistant message’s parts to drive per-tool progress indicators.

GenkitChatTransport takes url and an optional headers object or function for rotating auth tokens. To resume an earlier conversation, convert a snapshot’s messages with messagesFromSnapshot() and pass them to your chat binding’s messages option (for example, useChat({ id, messages })). When the user answers an interrupt through the SDK’s addToolResult, the transport returns the resolved tool output to the agent as a resume payload automatically.

On the server, this is the standard agent route shown above, backed by a session store so each sessionId keeps its own conversation; no extra wiring is required.