Skip to content

docs: clarify agent tool state options#3754

Merged
seratch merged 2 commits into
openai:mainfrom
william-xue:docs/agent-tool-state-options
Jul 8, 2026
Merged

docs: clarify agent tool state options#3754
seratch merged 2 commits into
openai:mainfrom
william-xue:docs/agent-tool-state-options

Conversation

@william-xue

Copy link
Copy Markdown
Contributor

What

Clarify that agent.as_tool() state options such as session, previous_response_id, and conversation_id apply to the nested agent run started by the tool call.

Why

This avoids confusion about whether nested tool-agent state is shared with the parent run, and points readers back to the same state-management choices used with Runner.run.

Test

  • git diff --check
  • Checked docs/tools.md contains the new note and keeps the structured-input sentence.

@seratch seratch left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for adding this clarification. The state options do configure the nested Runner invocation and are not inherited automatically from the parent run.
However, the current statement that they "are not shared" is too absolute. Passing the same Session to the parent run and agent.as_tool(...) is an intentional supported workflow; #1550 added per-turn persistence specifically for this agent-as-tool use case.
Please revise the paragraph to say that parent conversation state is not inherited automatically, while noting that callers can explicitly pass the same session when shared client-managed history is desired. The guidance to avoid mixing client-managed sessions with server-managed continuation should remain.

Comment thread docs/tools.md Outdated
@seratch seratch added the documentation Improvements or additions to documentation label Jul 8, 2026
@seratch seratch enabled auto-merge (squash) July 8, 2026 23:22
@seratch seratch merged commit 158b2f4 into openai:main Jul 8, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants