Skip to content

docs: clarify agent runtime, handoff, HITL, and results flows#2596

Merged
seratch merged 1 commit intomainfrom
docs/runtime-flow-clarifications
Mar 4, 2026
Merged

docs: clarify agent runtime, handoff, HITL, and results flows#2596
seratch merged 1 commit intomainfrom
docs/runtime-flow-clarifications

Conversation

@seratch
Copy link
Member

@seratch seratch commented Mar 4, 2026

This pull request updates the Python documentation to make the SDK's runtime surfaces easier to navigate and reason about across multi-agent workflows. It rewrites the result guide around surface selection instead of a flat property inventory, clarifies handoff input typing and guardrail boundaries, expands the HITL guide around run-wide approvals and resumable flows, and tightens the docs for context, sessions, and model-input shaping so the guides agree on how state moves through a run.

The main changes are in docs/results.md, docs/human_in_the_loop.md, docs/handoffs.md, docs/context.md, and docs/agents.md, with supporting clarifications in docs/guardrails.md, docs/running_agents.md, docs/sessions/index.md, and the generated handoff reference docstrings in src/agents/handoffs/__init__.py.

Behavioral/documentation clarifications included in this PR:

  • handoff(input_type=...) is documented as the handoff tool-call payload schema rather than the next agent's main input.
  • HITL approvals are documented as run-wide across direct tools, handoffs, and nested Agent.as_tool() runs, including partial resolution and resume behavior.
  • Result surfaces now explain the relationship between input, to_input_list(), new_items, raw_responses, last_response_id, agent_tool_invocation, and streaming lifecycle caveats.
  • Context and session docs now distinguish local app context from conversation state, explain what RunContextWrapper exposes, and clarify when to use session_input_callback versus call_model_input_filter.
  • The agents guide now acts as a navigation hub for related runtime guides and calls out key agent configuration fields more explicitly.

@github-actions github-actions bot added bug Something isn't working documentation Improvements or additions to documentation feature:lite-llm labels Mar 4, 2026
@seratch seratch removed bug Something isn't working feature:lite-llm labels Mar 4, 2026
@seratch seratch merged commit d6f950d into main Mar 4, 2026
9 checks passed
@seratch seratch deleted the docs/runtime-flow-clarifications branch March 4, 2026 09:11
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.

1 participant