Working with Items

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.

An item list is the Agent SDK's representation of everything that has happened in an agent session — user messages, model responses, tool calls, tool results, and system events. It is append-only: each turn appends new items; past items are never mutated.

Item types#

Each item carries a turnIndex so you can group items by the turn they appeared in.

How items flow through a loop#

1. You provide an initial messages array on the first callModel() call.
2. The SDK converts them into items and appends the model's response.
3. If the model makes tool calls, the SDK executes them and appends the results.
4. callModel() returns the complete item list including the new turn.
5. You pass result.items as inputItems to the next call — no merging or slicing required.

// Turn 1
const r1 = await client.callModel({
  model: "anthropic/claude-opus-4.8",
  messages: [{ role: "user", content: "What is 12 × 34?" }],
  tools: [calculatorTool],
});

// Turn 2 — pass the full item list forward
const r2 = await client.callModel({
  model: "anthropic/claude-opus-4.8",
  inputItems: r1.items,  // includes user msg, tool call, tool result, assistant reply
  messages: [{ role: "user", content: "Now divide that by 6." }],
});

Reading items#

The item list is a plain array. You can inspect it to build UI, write logs, or make routing decisions.

for (const item of result.items) {
  if (item.type === "message" && item.role === "assistant") {
    console.log("Model said:", item.content);
  }
  if (item.type === "tool_call") {
    console.log("Tool called:", item.name, item.arguments);
  }
  if (item.type === "tool_result") {
    console.log("Tool returned:", item.output);
  }
}

Slicing and replay#

Because the list is append-only, you can safely checkpoint it at any turn and resume from that point. Store result.items in a database or cache and pass it back to callModel() later to continue the session.

Item limits#

The SDK does not automatically truncate the item list. If a session grows long enough that the serialized history exceeds the model's context window, the request fails with an upstream_error from the provider. Handle this by summarising older turns and replacing them with a condensed message item before continuing.

Also see#

• Call Model — the callModel() API.
• Message Formats — supported content types within items.
• API Reference — full type definitions.