Messages
Understand the Message type — the permanent API surface for agent conversations.
Message Types
The Message union type represents all conversation entries. Messages are stored in Redis, appear in traces, and are used for replays. This is a permanent API surface.
type Message =
| UserMessage
| AssistantTextMessage
| AssistantToolCallMessage
| ToolResultMessage;UserMessage
interface UserMessage {
role: 'user';
content: string;
}AssistantTextMessage
A text response from the LLM (no tool calls):
interface AssistantTextMessage {
role: 'assistant';
content: string;
}AssistantToolCallMessage
The LLM wants to call one or more tools:
interface AssistantToolCallMessage {
role: 'assistant';
content: string | null;
toolCalls: ToolCallRequest[];
}
interface ToolCallRequest {
id: string;
name: string;
input: unknown;
}ToolResultMessage
The result of a tool execution:
interface ToolResultMessage {
role: 'tool';
toolCallId: string;
name: string;
content: string;
isError: boolean;
}Message Flow
A typical agent run produces this message sequence:
UserMessage → "Find the price of item X"
AssistantToolCall → toolCalls: [{ name: 'lookup', input: { name: 'X' } }]
ToolResultMessage → { name: 'lookup', content: '{"price": 29.99}' }
AssistantText → "Item X costs $29.99"Accessing Messages
Messages are available in the run state and test results:
import { createTestHarness, createMockLLM } from '@ahzan-agentforge/core';
const harness = createTestHarness({ agent: myAgentConfig, llm: mockLLM });
const result = await harness.run({ task: 'test' });
for (const msg of result.messages) {
console.log(`${msg.role}: ${msg.content ?? msg.toolCalls?.length + ' tool calls'}`);
}