Messages represent the conversation between users and agents. All messages follow a structured format with roles and content parts.
Message Type
type Message =
| SystemMessage
| UserMessage
| AssistantMessage
| ToolMessage
role field.
System Message
Contains system-level instructions or context.
Array of text content parts
{
role: 'system',
content: [
{
type: 'text',
text: 'You are a helpful coding assistant.'
}
]
}
User Message
Contains input from the user.
content
(TextPart | ImagePart | FilePart)[]
required
Array of content parts (text, images, or files)
{
role: 'user',
content: [
{
type: 'text',
text: 'Create a TypeScript config file'
},
{
type: 'image',
image: 'data:image/png;base64,...',
mediaType: 'image/png'
}
]
}
Assistant Message
Contains the agent’s response.
content
(TextPart | ReasoningPart | ToolCallPart)[]
required
Array of content parts (text, reasoning, or tool calls)
{
role: 'assistant',
content: [
{
type: 'text',
text: 'I will create the config file now.'
},
{
type: 'tool-call',
toolCallId: 'call_123',
toolName: 'write_file',
input: {
path: 'tsconfig.json',
content: '{"compilerOptions":{}}'
}
}
]
}
Contains the result of a tool execution.
ID matching the tool call from the assistant message
Name of the tool that was executed
content
ToolResultOutput[]
required
Array of output results from the tool
{
role: 'tool',
toolCallId: 'call_123',
toolName: 'write_file',
content: [
{
type: 'json',
value: {
success: true,
path: 'tsconfig.json'
}
}
]
}
Content Parts
Content is broken into typed parts that can be mixed in messages.
Text Part
Optional provider-specific metadata
{
type: 'text',
text: 'Create a new file'
}
Image Part
Image data as base64 data URI or URL object
MIME type of the image (e.g., image/png, image/jpeg)
Optional provider-specific metadata
{
type: 'image',
image: 'data:image/png;base64,iVBORw0KGgoAAAANS...',
mediaType: 'image/png'
}
File Part
File data as base64 data URI or URL object
Optional provider-specific metadata
{
type: 'file',
data: 'data:application/pdf;base64,JVBERi0...',
filename: 'document.pdf',
mediaType: 'application/pdf'
}
Reasoning Part
Contains the agent’s reasoning or thinking process.
Optional provider-specific metadata
{
type: 'reasoning',
text: 'I need to check if the file exists before modifying it...'
}
Represents a tool invocation by the agent.
Unique identifier for this tool call
input
Record<string, unknown>
required
Input parameters for the tool
Optional provider-specific metadata
Whether the provider executed this tool call
{
type: 'tool-call',
toolCallId: 'call_abc123',
toolName: 'run_terminal_command',
input: {
command: 'npm test',
process_type: 'SYNC'
}
}
Tool execution results can be JSON or media data.
JSON Output
JSON value returned by the tool
{
type: 'json',
value: {
success: true,
exitCode: 0,
stdout: 'All tests passed'
}
}
Base64-encoded media data
MIME type (e.g., image/png, application/pdf)
{
type: 'media',
data: 'iVBORw0KGgoAAAANSUhEUgA...',
mediaType: 'image/png'
}
Auxiliary Message Data
All message types include optional metadata fields:
Provider-specific options and metadata
Tags for categorizing or filtering messages (e.g., USER_PROMPT, SYSTEM)
Unix timestamp (ms) when the message was added to history. Used for prompt cache expiry detection.
timeToLive
'agentStep' | 'userPrompt'
deprecated
Use tags instead
Building Messages
Simple Text Message
const result = await client.run({
agent: 'base',
prompt: 'Create a hello world script'
})
Multimodal Message with Images
const result = await client.run({
agent: 'base',
prompt: 'Fix the bug shown in this screenshot',
content: [
{
type: 'text',
text: 'Fix the bug shown in this screenshot'
},
{
type: 'image',
image: 'data:image/png;base64,iVBORw0KG...',
mediaType: 'image/png'
}
]
})
Continuing with Previous Messages
const firstRun = await client.run({
agent: 'base',
prompt: 'Create a file'
})
// The message history is preserved in sessionState
const secondRun = await client.run({
agent: 'base',
prompt: 'Now add tests',
previousRun: firstRun // Includes full message history
})
Accessing Message History
const result = await client.run({
agent: 'base',
prompt: 'Write some code'
})
if (result.sessionState) {
const messages = result.sessionState.mainAgentState.messageHistory
for (const message of messages) {
if (message.role === 'user') {
console.log('User:', message.content)
} else if (message.role === 'assistant') {
for (const part of message.content) {
if (part.type === 'text') {
console.log('Agent:', part.text)
} else if (part.type === 'tool-call') {
console.log('Tool call:', part.toolName, part.input)
}
}
} else if (message.role === 'tool') {
console.log('Tool result:', message.toolName, message.content)
}
}
}
