Messages Overview

Messages are the building blocks of an agent's context. They make up the entirety of what your agent knows and can reference during execution.

The first message contains your system's initial input—this could be instructions you provide directly or input provided by an upstream process. As your agent executes, it adds new messages to capture everything that happens: tool outputs, intermediate results, and the agent's own responses. This creates a growing timeline of context that helps the agent make informed decisions at each step.

Messages are always attached to threads, and together they form the complete picture of what your agent knows and has accomplished during its execution.

When Messages are appended to Threads

Messages are automatically added to threads in three scenarios:

1. Initial input — The starting message provided by the user or an upstream system that triggers the agent's execution
2. Tool execution — Each tool's output is captured and appended as a new message, preserving the results for future reference
3. Final response — The agent's concluding output is added as the last message, completing the execution record

Create a Message & Add it to a Thread

NOTE: Messages must be attached to threads. See the threads page to learn how to create a thread

from seekrai import SeekrFlow

thread_id = "your_thread_id"

message = client.agents.threads.retrieve_message(
    thread_id=thread_id,
    message_id=message.id
)
print("Message retrieved!")
print(f"Thread ID: {message.thread_id}, Message ID: {message.id}") # If you're working with multiple threads, printing both IDs can help with tracking

Retrieve a Message

message = client.agents.threads.retrieve_message(
    thread_id=thread.id,
    message_id=message.id
)
print("Message retrieved!")
print(f"Thread ID: {message.thread_id}, Message ID: {message.id}") # If you're working with multiple threads, printing both IDs can help with tracking

Retrieve all Messages from a Thread

thread_id = "your_thread_id"
message_id = "your_message_id"


# List all messages in a thread
messages = client.agents.threads.list_messages(thread_id=thread_id)
print(f"Messages in thread {thread_id}:")
for message in messages:
    print(f"Message ID: {message.id}")
    print(f"Role: {message.role}")
    print(f"Content: {message.content}")
    print("-" * 10)

Update a Message

thread_id = "your thread id"
message_id = "your message id"

updated_message = client.agents.threads.update_message(
    thread_id=thread_id,
    message_id=message_id,
    content="What can you help me with?"
)
print(f"Message updated in thread {thread_id}!")
print(f"Message ID: {updated_message.id}")
print(f"New Content: {updated_message.content}")

Delete a Message

thread_id = "your thread id"
message_id = "your message id"

deleted_status = client.agents.threads.delete_message(
    thread_id=thread_id,
    message_id=message_id
)
print(f"Message {message_id} deleted from thread {thread_id}!")

Source tracking in file search responses

When an agent uses file search, each retrieved chunk's source tracking fields are appended to the assistant message content:

Use chunk_id with GET /v1/flow/vectordb/{database_id}/chunk/{chunk_id} to retrieve the file_id and download the original source document.

Message data structure

class ThreadMessage(BaseModel):
    id: str
    object: str = 'thread.message'
    created_at: datetime
    thread_id: str
    role: str  # e.g., 'user', 'assistant'
    content: ThreadMessageContentType
    agent_id: Optional[str]
    run_id: Optional[str]
    meta_data: dict[str, Any]