> ## 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.

Without conversation, each `Run` call is stateless — the agent has no memory of previous turns.

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.NewConversation(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. Increase for long sessions; decrease to control token usage. |
| `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.

<Note>
  Conversation history is prepended to every LLM call. Token usage grows with each turn — keep `Size` as low as your task allows and call `Clear` at session end.
</Note>

## 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"},
}

agentRun, err := a.Run(ctx, "I'm Alice. Remember that.", opts)
result, err := agentRun.Get(ctx)

agentRun, err = a.Run(ctx, "What's my name?", opts)
result, err = agentRun.Get(ctx) // 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` is set — the SDK detects the mismatch between a non-distributed backend and a split agent/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 [Distributed Execution](/advanced/distributed-execution) 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" horizontal>
    Redis-backed multi-turn history
  </Card>

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

## Related

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

  <Card title="Distributed Execution" icon="server" href="/advanced/distributed-execution" horizontal>
    Redis conversation with remote workers
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.