> ## Documentation Index
> Fetch the complete documentation index at: https://s2.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Use S2 as the event log for agent sessions, so chats, tool calls, and state can be streamed live, resumed, and replayed later.

The [typical pattern](https://s2.dev/blog/agent-sessions) is a stream per agent run.

Each invocation gets its own stream (`s2://my-basin/agents/{run-id}`) containing an ordered log of everything that happened — tool calls, LLM responses, state changes.

Streams can be [created automatically](/concepts/streams#creation) on first append or read, to simplify setup.

## Architecture

```mermaid theme={null}
graph LR
    A[agent] -->|append| S[s2://my-basin/agents/run-123]
    S -->|read SSE| C[client UI]

    subgraph infra["s2.dev"]
        S
    end
```

## Chat / LLM token streaming

The agent (or your backend) appends tokens to a stream as they're generated. The client opens a [read session](/sdk/reading) and renders them as they arrive. If the client disconnects and reconnects, it can easily resume from the last sequence number it processed by starting a new read session from that position.

<Tip>
  There's a ready-made integration for doing this with the Vercel AI SDK: [`@s2-dev/resumable-stream`](/integrations/vercel-ai-sdk).
</Tip>

## Agent logs and debugging

Actions the agent takes — tool invocations, API calls, intermediate reasoning — can be appended as structured records using [headers](/concepts/records). This gives you an audit trail for each run. Read the stream later to debug failures, or follow it live to watch an agent work. See the [agent session example](/integrations/vercel-ai-sdk#example) for a working implementation with the Vercel AI SDK.

<video controls className="w-full aspect-video rounded-xl" src="https://mintcdn.com/streamstore/7rEnITchd34f8M2P/videos/agents-demo-2.mp4?fit=max&auto=format&n=7rEnITchd34f8M2P&q=85&s=6168244b306f84c5e954c9dc099fe3de" data-path="videos/agents-demo-2.mp4" />

## State and context storage

A stream can serve as an append-only log of state changes for an agent session. Instead of overwriting state in a database, append each change as a record. Replay the stream to reconstruct state at any point — essentially event sourcing at the session level.

For long-running sessions, [external snapshots](/concepts/snapshots#external-snapshots) can speed up reconstruction while the stream remains the durable history.

<video controls className="w-full aspect-video rounded-xl" src="https://mintcdn.com/streamstore/7rEnITchd34f8M2P/videos/agents-demo-1.mp4?fit=max&auto=format&n=7rEnITchd34f8M2P&q=85&s=a3aedfade496606f2ab8705851246f3e" data-path="videos/agents-demo-1.mp4" />

## Multi-agent coordination

When multiple agents need to communicate, S2 streams provide natural coordination primitives. Use a shared stream as a message bus between agents, with per-agent streams for private memory. The ordered log guarantees all agents see events in the same order. See the [dinner party example](/integrations/vercel-ai-sdk#example) for a multi-agent implementation with the Vercel AI SDK.

<video controls className="w-full aspect-video rounded-xl" src="https://mintcdn.com/streamstore/7rEnITchd34f8M2P/videos/agents-demo-3.mp4?fit=max&auto=format&n=7rEnITchd34f8M2P&q=85&s=c02fbcc145136d65cb6889adfea29214" data-path="videos/agents-demo-3.mp4" />

## Getting started

If you're already building with the Vercel AI SDK, see the page on how we [integrate](/integrations/vercel-ai-sdk).

For custom setups, this flow can be modeled directly from the CLI:

```bash theme={null}
# Create a basin with auto-stream creation
s2 create-basin agent-runs --create-stream-on-append

# Agent appends (from your backend)
echo "tool_call: search('weather in SF')" \
    | s2 append s2://agent-runs/session-abc

# Client reads (from your frontend, using the token you issued)
s2 read -s0 s2://agent-runs/session-abc
```

In production, you would likely want to build around these same methods via our SDKs -- in particular, via the [Producer API](/sdk/appending#producer), which handles batching and pipelining automatically.