Conversations

Conversations enable agents to maintain context across multiple interactions. Without conversations, every message would be like talking to someone with amnesia. With conversations, agents remember what you’ve discussed and build on it.

What is a Conversation?

A conversation is a persistent thread of messages between a user and an agent. It functions like a chat thread in a messaging app: every exchange stays in context so the agent can refer back to earlier messages. Each conversation records the full set of messages, the tools invoked, the context needed for continuity, and the session that identifies the interaction.

Why Conversations Matter

Conversations matter because they turn isolated questions into coherent, multi-turn dialogues. The two effects below show the difference between stateless and stateful interactions.

Context Preservation

Without memory, an agent can answer a single question but loses track of what was just said. With a conversation, pronouns and follow-ups resolve naturally because the agent still has the prior turn in context.

Without Conversations:

With Conversations:

Multi-turn Interactions

Conversations enable complex, multi-step workflows where each step depends on what came before. The agent does not need the user to repeat the customer name on every turn because it can read the earlier turns.

For example, a support workflow might flow like this:

1. User asks for customer info
2. Agent retrieves it
3. User asks for their recent orders
4. Agent knows which customer (from step 1)
5. User asks to create a new order
6. Agent knows the customer and context

How Conversations Work

A conversation is created or reused automatically when an agent receives a message. The platform then appends each new message, reads the recent history, and persists the result so the next turn can continue from the same state.

Conversation Lifecycle

The lifecycle of a conversation follows the natural arc of an interaction:

1. User initiates interaction with an agent
2. System creates or retrieves active conversation
3. Messages are added to the conversation
4. Agent reads history for context
5. Conversation persists across multiple messages
6. Conversation ends when marked inactive or times out

Session Management

A session ties together the three pieces of identity that make a conversation unique: the channel where the interaction happens, the user who is interacting, and the agent being addressed. The platform combines these into a single Session ID.

Session ID format: {channel}:{user_id}:{agent_name} → chat:john@example.com:customer_support_agent

Conversation Modes

Agents can share or isolate conversation history depending on the use case. The same agent can run in per-user, shared, or trigger-scoped modes by adjusting the persist_user_history setting.

1. Per-User Conversations

Per-user conversation is the default behavior for most agents. Each user has a separate conversation thread, so messages and context never mix between users. This preserves privacy and prevents one user’s history from influencing another user’s results.

Common use cases:

• Customer support chat
• Personal assistants
• User-specific workflows

2. Shared Conversations

Shared conversation mode uses a single conversation thread across all users. Everyone sees the same history, which is useful for team collaboration but requires careful permission management because earlier user messages become visible to later users.

Common use cases:

• Team assistants
• Shared project agents
• Collaborative workflows

Configuration:

3. Conversation per Trigger

For scheduled and document event agents, history can be scoped either per trigger owner or shared across all triggers. The behavior is controlled by the persist_user_history checkbox in the Agent DocType.

Example:

Agent: Invoice Validator (runs on invoice submission)
Per-User Mode: Separate history for each user who submits invoices
Shared Mode: Single history tracking all invoice validations

Agent Conversation DocType

Conversations are stored in Desk → Huf → Agent Conversation. This DocType stores the metadata that links a session to its messages and lets administrators inspect, filter, and manage active or inactive threads.

Key Fields

Viewing Conversations

You can inspect conversations directly from Desk. Filtering by agent, user, or date makes it easy to find the thread you need.

In Desk:

1. Navigate to Huf → Agent Conversation
2. Filter by agent, user, or date
3. Click a conversation to see all messages

A conversation contains several kinds of entries:

Conversation History Management

History management controls how much of the conversation the agent loads into the prompt on each turn. A longer history gives more context, but it also increases token usage and can eventually hit model limits.

History Length

Agents load recent messages for context. The exact number is configurable per agent, and the loader stops before exceeding model token limits.

Limiting history matters for three reasons:

• Token costs — More history means more tokens per request, which increases costs.
• Context window — Models have a maximum token limit that history must share with instructions and the current prompt.
• Relevance — Very old messages often add noise rather than useful context.

History in Prompts

When an agent runs, the platform formats the recent history and includes it in the prompt. The agent can then resolve references like “their” because the earlier customer lookup is still visible.

The agent sees the full context and understands “their” refers to CUST-001.

Conversation Persistence

Persistence determines whether an agent remembers earlier turns or treats every request as independent. Enabling persistence is usually the right choice for chat and support agents, while disabling it keeps automated or batch tasks isolated.

When to Persist

Enable conversation persistence (persist_conversation=1) when:

• Multi-turn interactions are expected
• Context from previous messages matters
• Users will reference earlier discussion
• You want continuity across sessions

Disable persistence (persist_conversation=0) when:

• Each request is independent
• No context is needed between calls
• You are processing batch or automated tasks
• Privacy requires isolation between requests

Persistence Settings

In the Agent DocType, two fields control how history is stored and shared:

The combined effect of these flags is:

persist_conversation = 1, persist_user_history = 1:
→ Each user has their own conversation history

persist_conversation = 1, persist_user_history = 0:
→ All users share one conversation history

persist_conversation = 0:
→ No history, every message is independent

Agent Message DocType

Individual messages are stored in Agent Message. Each record is a single turn in a conversation and links back to the parent conversation and the Agent Run that produced it.

Key Fields

Message Kinds

The Kind field classifies each entry so the agent and the UI can render or use it appropriately.

Cost Implications

Because every message in history is added to the prompt, conversation length has a direct impact on token cost. Understanding that relationship helps you set history limits and choose the right strategy for each agent.

Token Usage

Conversations affect token costs in three ways:

• History tokens — Every message in history adds to the prompt.
• Cumulative cost — Longer conversations mean more tokens are sent on each new message.
• Exponential growth — Each new message includes all previous ones, so cost rises with conversation length.

Example:

Cost Optimization

You can keep costs under control without losing usefulness by managing how much history is retained and how conversations end:

1. Limit history length — Cap prior messages at 10–20 to keep prompt size predictable and costs under control.
2. Summarize old messages — Condense earlier context into a short summary instead of replaying every turn.
3. End conversations — Mark completed conversations inactive so they stop accumulating tokens.
4. Use stateless agents — For simple, independent requests, disable persistence entirely.
5. Monitor costs — Check Agent Run logs for token usage and trends.

Managing Conversations

Conversations are largely automatic, but administrators can start, end, or reset them when needed.

Starting a Conversation

Conversations start automatically when:

• A user sends a first message in chat
• An agent is triggered by an event or schedule
• An API call reaches the agent with a new session

No manual setup is required—the system creates the conversation and session for you.

Ending a Conversation

A conversation should be marked inactive once the task is finished, the user leaves, a timeout expires, or a reset is requested. Ending a conversation stops it from growing further and keeps future turns from inheriting stale context.

End a conversation manually:

1. Open Agent Conversation in Desk
2. Find the conversation
3. Uncheck Is Active
4. Save

End a conversation programmatically:

conversation = frappe.get_doc("Agent Conversation", conversation_name)
conversation.is_active = 0
conversation.save()

Clearing History

To reset an agent’s memory, mark the existing conversation as inactive. The next interaction will create a fresh conversation, while the old one remains available for audit.

1. Mark conversation Is Active = 0
2. The next interaction creates a new conversation
3. The old conversation remains in logs for audit

Conversation Strategies

Different interaction patterns call for different conversation configurations. Choose a strategy based on whether the task is one-off, long-running, or bounded by a single session.

Short Conversations

Short-conversation strategy suits one-off questions and independent requests where earlier context is unlikely to matter.

Configuration:

• Focus on clear, complete requests

Use cases:

• FAQ agents
• Simple data retrieval
• Batch processing

Long Conversations

Long-conversation strategy supports complex, multi-step interactions where context across many turns is essential.

Configuration:

Use cases:

• Customer support sessions
• Troubleshooting workflows
• Consultative interactions

Session-Based

Session-based strategy fits task-oriented interactions that should persist while the user is active but expire cleanly afterward.

Configuration:

Use cases:

• Form filling assistance
• Guided workflows
• Multi-step processes

Troubleshooting

When conversations behave unexpectedly, the cause usually falls into one of four areas: persistence settings, history length, session identity, or message storage. The checklist below helps you isolate each issue.

Agent doesn’t remember context:

Costs are too high:

Wrong conversation retrieved:

Messages not appearing:

Best Practices

Following a few design habits will keep conversations useful, private, and cost-effective.

Conversation Design

User Experience

A good conversation UI sets expectations and gives users control:

• Clear boundaries — Let users know when a new conversation starts
• Reset option — Provide a way to start fresh
• Context cues — Show conversation history in the UI
• Timeout warnings — Notify users when sessions expire

Performance

Performance improves when history is fetched and stored efficiently:

• Batch reads — Fetch history in efficient batches
• Lazy loading — Load history only when needed
• Cache strategy — Cache conversation metadata
• Archive old — Move inactive conversations to archives

What’s Next?

Now that you understand conversations:

• Triggers - Running agents automatically
• Agents - Configure conversation settings
• Monitoring - Track conversation costs
• Creating Agents - Design conversation flow

Questions about conversations? Check GitHub discussions .