Conversation

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 with a conversation.Config:

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

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.

Conversation ID

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

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):

docker run --rm -p 6379:6379 redis:latest

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.

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

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.

Custom backend

Implement interfaces.Conversation:

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

Redis-backed multi-turn history

Stream + Conversation

Streaming with persisted history

Memory

Long-term facts across separate runs

Distributed Execution

Redis conversation with remote workers

Overview

Getting Started

Runtimes

Features

Advanced

Observability

Testing & Evaluation

Production

Reference Apps

Conversation

Enable

Conversation ID

Backends

Remote workers

Lifecycle

Custom backend

Example

Conversation

Stream + Conversation

Memory

Distributed Execution

​Enable

​Conversation ID

​Backends

​Remote workers

​Lifecycle

​Custom backend

​Example

Conversation

Stream + Conversation

​Related

Memory

Distributed Execution

Enable

Conversation ID

Backends

Remote workers

Lifecycle

Custom backend

Example

Related