Skip to content

docs: Clarify new_items output conditions for improved developer experience #1352

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

docs: Clarify new_items output conditions for improved developer experience #1352

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 21 additions & 8 deletions docs/results.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,14 +28,27 @@ The [`last_agent`][agents.result.RunResultBase.last_agent] property contains the

## New items

The [`new_items`][agents.result.RunResultBase.new_items] property contains the new items generated during the run. The items are [`RunItem`][agents.items.RunItem]s. A run item wraps the raw item generated by the LLM.

- [`MessageOutputItem`][agents.items.MessageOutputItem] indicates a message from the LLM. The raw item is the message generated.
- [`HandoffCallItem`][agents.items.HandoffCallItem] indicates that the LLM called the handoff tool. The raw item is the tool call item from the LLM.
- [`HandoffOutputItem`][agents.items.HandoffOutputItem] indicates that a handoff occurred. The raw item is the tool response to the handoff tool call. You can also access the source/target agents from the item.
- [`ToolCallItem`][agents.items.ToolCallItem] indicates that the LLM invoked a tool.
- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] indicates that a tool was called. The raw item is the tool response. You can also access the tool output from the item.
- [`ReasoningItem`][agents.items.ReasoningItem] indicates a reasoning item from the LLM. The raw item is the reasoning generated.
The [`new_items`][agents.result.RunResultBase.new_items] property contains a list of [`RunItem`][agents.items.RunItem]s generated during the run. The type of `RunItem` you receive depends on the agent's action.

- **When the LLM gives a direct answer:**

- [`MessageOutputItem`][agents.items.MessageOutputItem] indicates a final message from the LLM. The raw item is the message generated.

- **When the LLM uses a tool:**

- [`ToolCallItem`][agents.items.ToolCallItem] indicates that the LLM has decided to invoke a tool.

- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] indicates that the tool was called and has returned a response. The raw item is the tool response.

- **When a handoff occurs:**

- [`HandoffCallItem`][agents.items.HandoffCallItem] indicates that the LLM called the handoff tool.

- [`HandoffOutputItem`][agents.items.HandoffOutputItem] indicates that a handoff occurred. The raw item is the tool response to the handoff tool call.

- **When the LLM is reasoning internally:**

- [`ReasoningItem`][agents.items.ReasoningItem] indicates a reasoning item from the LLM. The raw item is the reasoning generated. This item appears when the LLM produces an internal thought process before deciding on its next action.

## Other information

Expand Down