> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with items

> Render typed messages, reasoning, tool activity, errors, and final outputs.

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`:

```typescript theme={null}
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:

```typescript theme={null}
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.

## Related guides

* [Streaming](./agent-sdk-streaming)
* [Tools](./agent-sdk-tools)
* [Lifecycle hooks](./agent-sdk-lifecycle-hooks)