tai/research/cap-protocol/openai-agents-python-tools-agent-as-tool.md

OpenAI Agents SDK: Tools (agents as tools)

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	cap-protocol
Document type	Source Dossier
Tier	1
Source title	OpenAI Agents SDK: Tools (agents as tools)
Source URL	https://openai.github.io/openai-agents-python/tools/
Source publisher / author	OpenAI
Source type	vendor docs
Source date (published)	Unknown — not stated
Date researched	2026-10-25
Researched by	tai (agent), model: Claude Sonnet 5, on behalf of retoor
Research method	direct page fetch
Confidence	High
Status	Active

Summary

The SDK page that defines Agent.as_tool(): exposing a specialist agent to a manager as a callable tool instead of handing the conversation over.

Key findings

• The agent-as-tool run has its own state: the parent run's conversation state is not inherited automatically; pass the same session to share client-managed history.
• The nested run's final output is returned to the parent as the tool result; custom_output_extractor can reshape it first.
• is_enabled takes a boolean, a callable or an async function; disabled tools are completely hidden from the LLM at runtime.
• By default the tool expects an object with one string field input; a Pydantic model or dataclass via parameters replaces that, and include_input_schema=True adds the JSON Schema to the nested input.
• If needs_approval requires a decision, the nested run pauses and the pending items surface in result.interruptions.
• Guidance: use a central agent that orchestrates specialists 'instead of handing off control'.

Pros / strengths

Concrete, small API that names the knobs a delegation tool needs: input schema, output extractor, enable switch, approval pause.

Cons / limitations / caveats

Describes the SDK's API, not measured outcomes; the handoff comparison lives on another page.

Relevance to tai

Template for the shape of a tai ask_agent tool: structured input, nested run in its own context, only the final output returned, an enable switch and an approval hook.

Changelog

Date	Change
2026-10-25	Initial dossier created.