Working with items

Use items to build a structured agent timeline without parsing provider-specific events. Streaming and completed runs expose the same ordered AgentItem<TOutput> contract.

Item types

AgentItem<TOutput> is a discriminated union:

`type`	Important fields	Represents
`message`	`role`, `content`	Assistant or conversation text
`reasoning`	`text`	Reasoning supplied by the model
`tool_call`	`toolCallId`, `name`, `input`	A proposed tool invocation
`tool_result`	`toolCallId`, `name`, `output`	A completed tool invocation
`error`	`message`, optional tool details	A provider or tool error
`output`	`value`	The parsed final agent output

Render a streamed timeline

TypeScript narrows each item from its type:

const stream = agent.stream({ input, client });

for await (const item of stream.getItemsStream()) {
  switch (item.type) {
    case "message":
      renderAssistantMessage(item.content);
      break;
    case "reasoning":
      renderReasoning(item.text);
      break;
    case "tool_call":
      renderToolCall(item.toolCallId, item.name, item.input);
      break;
    case "tool_result":
      renderToolResult(item.toolCallId, item.output);
      break;
    case "error":
      renderError(item.message);
      break;
    case "output":
      renderFinalOutput(item.value);
      break;
  }
}

Read items after completion

The completed result contains the same ordered item shapes:

const completed = await stream.getResult();

for (const item of completed.items) {
  saveTimelineItem(completed.run.id, item);
}

This lets a product render live activity and later rebuild the same timeline from persisted run state.

Access provider-specific data

Provider output is normalized into portable item types. When an integration still needs a provider-specific field, normalized provider items retain the original payload in rawProviderItem. Keep product logic on the portable fields where possible. Treat rawProviderItem as an escape hatch for provider-specific integrations, not as the default application contract.

Start Here

Build

Observe

Reference

Item types

Render a streamed timeline

Read items after completion

Access provider-specific data

​Item types

​Render a streamed timeline

​Read items after completion

​Access provider-specific data

​Related guides

Item types

Render a streamed timeline

Read items after completion

Access provider-specific data

Related guides