Best Practice for
Passing Conversation History
...
# ask-aij
jolly-eve-3916
07/31/2025, 10:12 AMBest Practice for
Passing Conversation History
to Voice Agent via
Participant Metadata
Hi, I'm building a voice
agent that needs access to
previous text conversation
history when a user starts a
voice call. I'm considering
two approaches:
1. Pass conversation history
in participant metadata when
generating the LiveKit token:
const token = new
AccessToken(apiKey,
apiSecret, {
identity: patientId,
metadata: JSON.stringify({
patientId,
threadId,
conversationHistory: [
{role: "user", content:
"Previous message 1"},
{role: "assistant",
content: "Previous response
1"},
// ... last 10-15
messages
]
}),
});
Then in the Python agent,
parse this metadata and load
it into ChatContext:
chat_ctx =
llm.ChatContext.empty()
for msg in
conversation_history:
chat_ctx.add_message(role
=msg["role"],
content=msg["content"])
agent = Agent(
instructions="...",
chat_ctx=chat_ctx,
)
2. Have the agent fetch
history via API after
connecting
My questions:
- Is approach #1 (metadata)
recommended for passing
conversation history?
- Are there any limitations
or concerns with including
~10-15 messages (approx
3-4KB) in participant
metadata?
- Is this the correct way to
initialize an Agent with
pre-existing ChatContext?
- Will the agent treat these
messages as actual
conversation history for
context, or do I need to
handle them differently?
Using LiveKit Python agents
v1.0+ with Anthropic LLM.
Thanks!
t
tall-airline-16756
07/31/2025, 10:12 AMThanks for reaching out, Albert. I'm an AI assistant and I'm here to help. Give me a moment while I research this topic.
tall-airline-16756
07/31/2025, 10:14 AMHere are the best practices and considerations for passing conversation history to a voice agent using participant metadata in LiveKit:
• Using Metadata for Conversation History: Participant attributes are recommended for passing user-specific data, such as conversation history, to agents. This avoids the need for additional API calls after connecting.
• Loading Conversation History: You can extract conversation history from metadata in your entrypoint function and initialize the
ChatContext Copy code
from livekit import agents
from livekit.agents import Agent, ChatContext, AgentSession
import json
class Assistant(Agent):
def __init__(self, chat_ctx: ChatContext) -> None:
super().__init__(chat_ctx=chat_ctx, instructions="You are a helpful voice AI assistant.")
async def entrypoint(ctx: agents.JobContext):
metadata = json.loads(ctx.job.metadata)
conversation_history = metadata.get("conversation_history", [])
initial_ctx = ChatContext()
for message in conversation_history:
initial_ctx.add_message(role=message["role"], content=message["content"])
session = AgentSession()
await session.start(
room=ctx.room,
agent=Assistant(chat_ctx=initial_ctx),
)truncateChatContext Copy code
chat_ctx.truncate(max_items=15)before_llm_cbctx.connect()mergeChatContext5 Views