Message Formats

Not yet available. The Agent SDK is tracked to be built — today, use the Client SDKs against the live chat completions API. The docs below describe the intended design.

Messages passed to callModel() follow the OpenAI chat format. Each message has a role and content. Content can be a plain string or an array of typed parts for multimodal inputs.

Roles#

String content#

The simplest form — a plain string:

{ role: "user", content: "What is the capital of Algeria?" }

Array content (multimodal)#

For vision-capable models, content can be an array of typed parts:

{
  role: "user",
  content: [
    { type: "text", text: "What's in this image?" },
    {
      type: "image_url",
      image_url: {
        url: "https://example.com/photo.jpg",
      },
    },
  ],
}

The SDK passes image parts through as-is to the underlying model. Only models with vision capability support image inputs — check the model catalog or filter by capability=vision.

Inline base64 images#

{
  type: "image_url",
  image_url: {
    url: `data:image/jpeg;base64,${base64String}`,
  },
}

System message#

Place the system message first. Pass it once — it does not need to repeat in subsequent turns when using inputItems.

const result = await client.callModel({
  model: "anthropic/claude-sonnet-5",
  messages: [
    {
      role: "system",
      content: "You are a helpful assistant. Respond in the user's language.",
    },
    { role: "user", content: "مرحبا! ما هو الذكاء الاصطناعي؟" },
  ],
});

Tool messages#

When callModel() executes a tool, it appends a tool_call item and a tool_result item to the item list. These are translated to tool role messages when the SDK sends the next model request — you don't need to construct them yourself.

Content limits#

The maximum total content size per call depends on the model's context window. Check GET /api/models/{slug} for context_window. The SDK does not automatically truncate — if the input exceeds the context window, the request fails with an upstream_error from the provider.

Also see#

• Working with Items — how messages become items.
• Text Generation — generation patterns.
• Multimodal — full guide to image inputs.
• API Reference — complete type definitions.