Chat context & history

Every session keeps one conversation history as an llm.ChatContext: the user and assistant messages, tool calls, and their outputs. The generation loop builds each reply's prompt from the current agent's instructions plus this shared history. This page is how you read it and seed it.

History is shared, not per-agent

There is one history per session, shared across every agent a handoff or task activates — swapping agents doesn't reset the conversation. An agent's own ChatContext seed (below) merges into that shared history; it doesn't give the agent a private transcript.

Read the conversation

session.History() returns the shared *llm.ChatContext. Iterate its items to log, summarize, or debug what was said:

for _, item := range session.History().Items() {
    if m, ok := item.(*llm.ChatMessage); ok {
        log.Printf("%s: %s", m.Role, m.TextContent())
    }
}

Items are typed — *llm.ChatMessage (with a Role of user/assistant/system and TextContent()), plus function-call and function-output items for tool activity.

Seed prior turns

To start a conversation with existing context — a prior session, a few-shot prime, a system preamble beyond instructions — set AgentOptions.ChatContext on the initial agent:

seed := llm.NewChatContext()
seed.AddMessage(llm.RoleUser, []any{"My name is Sam and I prefer metric units."})
seed.AddMessage(llm.RoleAssistant, []any{"Got it, Sam — I'll use metric."})

agent := agents.MustNewAgent(agents.AgentOptions{
    Instructions: "You are a helpful assistant.",
    ChatContext:  seed,
})

Next

• Agent sessions — where History() lives.
• Full API: Reference → AgentSession.