how do i insert a system message in the chat ctx at a specif LiveKit Community #ask-ai

Join Slack

how do i insert a system message in the chat ctx a...

# ask-ai

gorgeous-soccer-57984

09/17/2025, 6:59 AM

how do i insert a system message in the chat ctx at a specific postition

tall-airline-16756

09/17/2025, 6:59 AM

Thanks for reaching out, Dhruv. I'm an AI assistant and I'm here to help. Give me a moment while I research this topic.

tall-airline-16756

09/17/2025, 6:59 AM

I'd be happy to guide you on how to insert a system message into the chat context at a specific position. Here are a couple of friendly methods you can try: Method 1: Using
RemoteChatContext
The

RemoteChatContext.insert()

method is a great way to insert a system message right after a specific message ID. If you set

previous_item_id

None

(in Python) or

undefined

(in TypeScript), it will place the message right at the beginning of the chat context. Python Example:

Copy code

from livekit.agents import llm

# Create system message
system_message = llm.ChatMessage(
    role="system",
    content=["Your system instructions here"],
    id="custom_system_msg"
)

# Insert after a specific message ID, or at the head if None
remote_ctx = RemoteChatContext()
remote_ctx.insert(previous_item_id="target_msg_id", message=system_message)  # Insert after "target_msg_id"
# OR
remote_ctx.insert(previous_item_id=None, message=system_message)  # Insert at head

TypeScript Example:

Copy code

import { ChatMessage, RemoteChatContext } from 'livekit-agents';

const systemMessage = new ChatMessage({
  role: 'system',
  content: ['Your system instructions here'],
  id: 'custom_system_msg'
});

const remoteCtx = new RemoteChatContext();
remoteCtx.insert('target_msg_id', systemMessage);  // Insert after "target_msg_id"
// OR
remoteCtx.insert(undefined, systemMessage);  // Insert at head

Method 2: Direct Array Manipulation If you prefer, you can also directly work with the

ChatContext.items

array. This lets you insert a system message at any index you like using familiar array methods like

insert()

in Python or

splice()

in TypeScript. Python Example:

Copy code

# Insert at a specific index (e.g., index 1)
chat_ctx.items.insert(1, system_message)

TypeScript Example:

Copy code

// Insert at a specific index (e.g., index 1)
chat_ctx.items.splice(1, 0, systemMessage);

If anything feels unclear or you’d like me to walk you through it step-by-step, just let me know—I’m here to help! Sources: examples/voice_agents/llamaindex-rag/retrieval.py | agents/src/llm/remote_chat_context.test.ts

gorgeous-soccer-57984

09/17/2025, 7:00 AM

how do i replace a message in the chat_ctx

tall-airline-16756

09/17/2025, 7:01 AM

Hi there! To help you replace a message in the chat context, here are a couple of approaches depending on what you need: 1. Editing a Published Chat Message (User-Visible) If you want to update or correct a chat message you've already sent (like fixing a typo), you can use the

editChatMessage

method available in the LiveKit SDKs. This will update the message content and let everyone in the chat see the change. Node.js Example:

Copy code

await localParticipant.editChatMessage(editText, originalMessage);

Rust Example:

Copy code

local_participant.edit_chat_message(edit_text, original_message).await;

Python Example:

Copy code

# Use the EditChatMessageRequest to replace the message content

This method updates the message in the chat history and adds an edit timestamp, so everyone knows it was modified. 2. Replacing a Message in the LLM Agent's Chat Context If you're working with an AI agent and want to change a message inside its internal chat context, you can directly update the

ChatContext.items

array. Just find the message by its ID or index and change its content. Python Example:

Copy code

# Locate the message by ID or index
for item in chat_ctx.items:
    if item.id == "target_message_id":
        item.content = "New content here"
        break

Please feel free to reach out if you'd like me to walk you through any of these steps or if you have any other questions. I'm here to help! Sources: packages/livekit-rtc/src/proto/room_pb.ts | livekit-ffi/src/server/room.rs | livekit-rtc/livekit/rtc/_proto/room_pb2.pyi | Agents 0.x migration guide | LiveKit Docs | Agents v0.x migration guide - Node.js | LiveKit Docs

gorgeous-soccer-57984

09/17/2025, 7:48 AM

Copy code

<http://logger.info|logger.info>("Switching language to English as per user request.")
new_chat_ctx_dict = self.chat_ctx.to_dict()
new_chat_ctx_dict["items"][0]["content"] = [english_prompt]
new_chat_ctx_dict["items"][-1]["content"] = ["Hello"]
chat_ctx = llm.ChatContext.from_dict(new_chat_ctx_dict)
<http://logger.info|logger.info>(f"{chat_ctx.items[0]}")

await self.update_chat_ctx(chat_ctx)
<http://logger.info|logger.info>(f"{self.chat_ctx.items[0]}")
await self.session.generate_reply()

the chat ctx is not updating i have checked the logs

tall-airline-16756

09/17/2025, 7:49 AM

It looks like the chat context might not be updating because the

chat_ctx

property is actually a read-only view of the context. So, any direct changes you make to this instance won’t stick unless you handle them in a specific way. To help you get those updates applied smoothly, here’s what I recommend: 1. Start by using

.copy()

on the current

chat_ctx

to create a version you can modify. 2. Make the changes you need to that copied context. 3. Then, call

await self.update_chat_ctx(modified_context)

to save those updates. Here’s a quick example to illustrate:

Copy code

# Create a mutable copy
new_chat_ctx = self.chat_ctx.copy()

# Modify the content
new_chat_ctx.items[0].content = ["English prompt"]
new_chat_ctx.items[-1].content = ["Hello"]

# Update the chat context
await self.update_chat_ctx(new_chat_ctx)

Also, just a couple of things to double-check: • Make sure the agent isn’t in a state that blocks updates, like right after a session restart. • Keep an eye out for any

RealtimeError

exceptions in your logs when calling

update_chat_ctx

, as these might point to some provider-specific restrictions. If you run into any hiccups or have more questions, please don’t hesitate to reach out—I’m here to help! Sources: livekit-agents/livekit/agents/voice/agent_activity.py

gorgeous-soccer-57984

09/17/2025, 7:50 AM

after using copy how can i update the content of teh 0th item

tall-airline-16756

09/17/2025, 7:51 AM

Once you've created a copy of the chat context, you can easily update the content of the 0th item by modifying its

content

property directly. Here's a little example to guide you:

Copy code

# Create a mutable copy of the chat context
new_chat_ctx = self.chat_ctx.copy()

# Update the content of the 0th item
new_chat_ctx.items[0].content = ["Updated content for the 0th item"]

# Apply the updated chat context
await self.update_chat_ctx(new_chat_ctx)

If anything feels unclear or if you'd like me to walk you through this step-by-step, please don’t hesitate to ask. I’m here to help!

gorgeous-soccer-57984

09/17/2025, 7:55 AM

still ther eis not change

tall-airline-16756

09/17/2025, 7:56 AM

I don't have the answer you're looking for. You could also try asking your question: • in one of the other Slack channels or • to https://deepwiki.com/livekit/livekit_composite which is trained on all LiveKit source code If you find the answer, please post it here to help others!

4 Views

Open in Slack

Previous Next