Messages and History
Understand Anvia message objects and conversation history.
Anvia history is a plain Message[]. You choose where to store it, then pass it into each new prompt with .withHistory(...).
Message Roles
| Role | Shape | Use for |
|---|---|---|
system | { role: "system", content: string } | System-level instructions in raw message history |
user | { role: "user", content: UserContent[] } | User text, tool results, images, and documents |
assistant | { role: "assistant", content: AssistantContent[] } | Assistant text, reasoning, images, and tool calls |
Most application history contains user and assistant messages.
Text History
import type { Message } from "@anvia/core";
const history: Message[] = [
{
role: "user",
content: [{ type: "text", text: "My checkout failed." }],
},
{
role: "assistant",
content: [
{
type: "text",
text: "I can help. What error did you see?",
},
],
},
];You can create the same shape with helpers:
import { Message } from "@anvia/core";
const history = [
Message.user("My checkout failed."),
Message.assistant("I can help. What error did you see?"),
];Persisting History
response.messages contains only the new messages created by one run. Append those messages to your stored conversation.
const history = await conversations.loadMessages(conversationId);
const response = await agent
.prompt(userInput)
.withHistory(history)
.send();
await conversations.saveMessages(conversationId, [
...history,
...response.messages,
]);Persist the plain message objects returned by Anvia. JSON storage is enough for most applications.
Tool Calls In History
Tool calls are assistant content. Tool results are user content.
import type { Message } from "@anvia/core";
const historyWithToolCall: Message[] = [
{
role: "user",
content: [{ type: "text", text: "Where is order A-100?" }],
},
{
role: "assistant",
content: [
{
type: "tool_call",
id: "call_1",
function: {
name: "lookup_order",
arguments: { orderId: "A-100" },
},
},
],
},
{
role: "user",
content: [
{
type: "tool_result",
id: "call_1",
content: [{ type: "text", text: "{\"status\":\"shipped\"}" }],
},
],
},
{
role: "assistant",
content: [{ type: "text", text: "Order A-100 has shipped." }],
},
];Only create tool-call history yourself when importing an existing transcript or replaying a known run. For live runs, persist response.messages.
Attachments
User messages can include text, images, and documents:
import { Message, UserContent } from "@anvia/core";
const message = Message.user([
UserContent.text("Summarize this report."),
UserContent.documentUrl("https://example.com/report.pdf", "application/pdf", {
filename: "report.pdf",
}),
]);Provider support for attachments varies. Check the provider and model before building a workflow that depends on images or documents.
Next
Read Prompt Responses to see what an agent run returns.