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

# Conversation

> Persist message history across turns in the same session using in-memory or Redis backends

Conversation lets agents **carry message history across turns** — user messages, assistant replies, and tool results — so multi-step chats stay coherent without resending the full thread.

Use it for chat UIs, support bots, or any agent where the user sends several prompts in one session.

## Enable

Pass [`WithConversation`](/getting-started/configuration) with a [`conversation.Config`](https://pkg.go.dev/github.com/agenticenv/agent-sdk-go/pkg/conversation#Config):

```go theme={null}
import (
    "github.com/agenticenv/agent-sdk-go/pkg/agent"
    "github.com/agenticenv/agent-sdk-go/pkg/conversation"
    "github.com/agenticenv/agent-sdk-go/pkg/conversation/inmem"
)

conv := inmem.NewInMemoryConversation(inmem.WithMaxSize(100))

a, err := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithConversation(conversation.Config{
        Conversation: conv,
        Size:         20,
    }),
)
```

| Field             | Description                                                                                                                         |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `Conversation`    | Backend implementing [`interfaces.Conversation`](https://pkg.go.dev/github.com/agenticenv/agent-sdk-go/pkg/interfaces#Conversation) |
| `Size`            | Max past messages loaded for the LLM — defaults to **20** when zero                                                                 |
| `SaveOnIteration` | Persist after each tool round — useful when external consumers need live updates during multi-step runs                             |

Use `conversation.DefaultConfig(conv)` for SDK defaults with no overrides.

## Conversation ID

When conversation is enabled, pass the same session ID on every call to share history:

```go theme={null}
opts := &agent.AgentRunOptions{
    ConversationOptions: &agent.ConversationOptions{ID: "session-1"},
}

a.Run(ctx, "I'm Alice. Remember that.", opts)
a.Run(ctx, "What's my name?", opts) // receives: "Alice"
```

Different IDs are isolated sessions. Sub-agents always run without a conversation ID — they do not inherit the parent session history.

## Backends

| Backend   | Package                             | Use case                                               |
| --------- | ----------------------------------- | ------------------------------------------------------ |
| In-memory | `pkg/conversation/inmem`            | Single process — agent and worker together             |
| Redis     | `pkg/conversation/redis`            | Remote workers or split client/worker across processes |
| Custom    | Implement `interfaces.Conversation` | Your own store or distributed backend                  |

**Redis setup (local dev):**

```bash theme={null}
docker run --rm -p 6379:6379 redis:latest
```

<Warning>
  In-memory conversation fails at **build time** when `DisableLocalWorker` or `EnableRemoteWorkers` is set — the SDK detects the mismatch between a non-distributed backend and a remote-worker deployment. Use Redis (or another distributed backend) on both the agent and worker processes.
</Warning>

### Remote workers

Use Redis on both the agent and worker processes. Pass the same `conversation.Config` to `NewAgent` and `NewAgentWorker`. Set `SaveOnIteration: true` on the worker if external consumers need live history mid-run. See [Worker Separation](/advanced/worker-separation) for the full setup.

## Lifecycle

You own the conversation store. Call `Clear(ctx, id)` when ending a session — **the agent never clears history for you**.

<Note>
  With `SaveOnIteration: true` on the worker, history is written after each tool round so external consumers can read it mid-run. Without it, history is written only when the run completes. Set it on the worker, not the agent.
</Note>

## Custom backend

Implement [`interfaces.Conversation`](https://pkg.go.dev/github.com/agenticenv/agent-sdk-go/pkg/interfaces#Conversation):

```go theme={null}
type Conversation interface {
    AddMessage(ctx context.Context, id string, msg Message) error
    ListMessages(ctx context.Context, id string, opts ...ListMessagesOption) ([]Message, error)
    Clear(ctx context.Context, id string) error
    IsDistributed() bool
}
```

Set `IsDistributed()` to `true` for any backend that can be shared across processes. The SDK uses this to validate compatibility with remote-worker deployments. Pass the implementation in `conversation.Config.Conversation`.

## Example

<CardGroup cols={2}>
  <Card title="Conversation" icon="play" href="/examples/conversation">
    Redis-backed multi-turn history
  </Card>

  <Card title="Stream + Conversation" icon="play" href="/examples/stream-conversation">
    Streaming with persisted history
  </Card>
</CardGroup>

## Related

<CardGroup cols={2}>
  <Card title="Memory" icon="brain" href="/features/memory">
    Long-term facts across separate runs
  </Card>

  <Card title="Worker Separation" icon="server" href="/advanced/worker-separation">
    Redis conversation with remote workers
  </Card>

  <Card title="Streaming" icon="wave-pulse" href="/getting-started/streaming">
    Stream with conversation options
  </Card>

  <Card title="Configuration" icon="sliders" href="/getting-started/configuration">
    WithConversation reference
  </Card>
</CardGroup>