Inkdown
Start writing

OpenAI Agents Python

21 filesยท0 subfolders

Shared Workspace

OpenAI Agents Python
00_OVERVIEW.md

03_TOOL_SYSTEM

Shared from "OpenAI Agents Python" on Inkdown

Tool System - Comprehensive Deep Dive

Overview

The Tool system is one of the most powerful features of the OpenAI Agents SDK. Tools are functions or capabilities that agents can call to perform actions beyond just generating text. Think of tools as "skills" or "abilities" that you give to your agents - they can search the web, read files, execute code, call APIs, interact with databases, and much more.

Core Concepts

What is a Tool?

A tool is a callable function that an agent can invoke. When an agent needs to perform an action (like searching the web or reading a file), it can call a tool instead of trying to do everything through text generation.

Why Tools Matter:

  1. Action Capability - Agents can actually do things, not just talk about them
  2. Accuracy - Tools can provide precise, factual information
  3. Integration - Connect agents to external systems (databases, APIs, etc.)
  4. Efficiency - Delegating to specialized tools is often faster/better
01_AGENT_SYSTEM.md
02_RUNNER_SYSTEM.md
03_TOOL_SYSTEM.md
04_ITEMS_SYSTEM.md
05_GUARDRAILS.md
06_HANDOFFS.md
07_MEMORY_SESSIONS.md
08_MODEL_PROVIDERS.md
09_SANDBOX_SYSTEM.md
10_TRACING.md
11_RUN_STATE.md
12_CONTEXT.md
13_LIFECYCLE_HOOKS.md
14_CONFIGURATION.md
15_ERROR_HANDLING.md
16_STREAMING.md
17_EXTENSIONS.md
18_MCP_INTEGRATION.md
19_BEST_PRACTICES.md
20_ARCHITECTURE_PATTERNS.md
  • Reliability - Tools can have error handling and validation
    • Tool Types

    The SDK supports several types of tools:

    1. Function Tools - Python functions decorated with @function_tool
    2. Hosted Tools - OpenAI-hosted tools (file search, web search, code interpreter)
    3. MCP Tools - Tools from Model Context Protocol servers
    4. Agent Tools - Other agents exposed as tools
    5. Shell Tools - Command execution tools
    6. Computer Tools - Computer interaction tools
    7. Custom Tools - Custom tool implementations

    Function Tools

    Basic Function Tools

    The most common type is the function tool - a Python function decorated with @function_tool:

    Python

    How it works:

    1. The decorator converts the function into a FunctionTool instance
    2. The function's signature is analyzed to create a JSON schema
    3. The schema is exposed to the LLM so it knows how to call the tool
    4. When the LLM calls the tool, the function is executed with the provided arguments
    5. The return value is converted to a string and sent back to the LLM
    Function Tool Parameters

    Function tools can have various parameter types:

    Python

    Supported Parameter Types:

    • Basic types: str, int, float, bool
    • Optional types: Optional[T] or T | None
    • Collections: List[T], Dict[str, T]
    • Enums: Enum subclasses
    • Pydantic models: BaseModel subclasses
    • Dataclasses: @dataclass classes
    Context-Aware Function Tools

    Function tools can access the run context:

    Python

    Context provides:

    • context.context - Your custom context object
    • context.usage - Token usage tracking
    • context.approve_tool() / context.reject_tool() - Approval management
    • context.tool_name, context.tool_call_id - Tool metadata
    Tool Context

    For more detailed tool metadata, use ToolContext:

    Python

    ToolContext provides:

    • All of RunContextWrapper
    • tool_name - Name of the tool being called
    • tool_call_id - Unique ID for this tool call
    • tool_arguments - Raw JSON arguments
    • tool_call - The full tool call object
    • tool_namespace - Namespace if configured
    • run_config - Run configuration
    • agent - The agent calling the tool
    Async Function Tools

    Tools can be async:

    Python
    Tool Namespaces

    Organize tools into namespaces to avoid name collisions:

    Python

    Why use namespaces?

    • Avoid name collisions when tools have similar names
    • Organize tools logically
    • Make it clear which "domain" a tool belongs to
    • The LLM sees names like math.add and string.concatenate
    Dynamic Tool Enablement

    Tools can be dynamically enabled or disabled:

    Python

    Use cases:

    • Role-based access control
    • Feature flags
    • Context-dependent availability
    • A/B testing
    Tool Descriptions

    The function's docstring becomes the tool's description:

    Python

    Good descriptions:

    • Explain what the tool does
    • Explain when to use it
    • Explain what it returns
    • Keep it concise but informative
    Tool Error Handling

    Tools can raise errors:

    Python

    How errors are handled:

    1. The SDK catches the exception
    2. By default, formats it as an error message for the LLM
    3. The LLM can try again with different arguments
    4. You can customize error formatting with failure_error_function
    Custom Error Formatting
    Python
    Tool Output Types

    Tools can return different output types:

    Python

    Why use structured output?

    • Tell the LLM what type of content to expect
    • Enable multimodal interactions
    • Provide file outputs for further processing
    • Better integration with model capabilities

    Hosted Tools

    OpenAI Hosted Tools

    OpenAI provides several hosted tools that you can use:

    Python

    FileSearchTool:

    • Search through uploaded documents
    • Supports vector search
    • Good for RAG (Retrieval-Augmented Generation)

    WebSearchTool:

    • Search the web in real-time
    • Good for current information
    • Supports filters and location

    CodeInterpreterTool:

    • Execute Python code
    • Good for data analysis
    • Supports file operations
    Image Generation Tool
    Python

    MCP Tools

    Model Context Protocol

    MCP is a standard protocol for exposing tools to AI models:

    Python

    MCP Benefits:

    • Standardized tool interface
    • Language-agnostic
    • Easy tool sharing
    • Community ecosystem
    MCP Configuration
    Python
    MCP Tool Filtering
    Python

    Agent as Tool

    Exposing Agents as Tools

    Agents can be exposed as tools to other agents:

    Python

    How it works:

    1. The agent is wrapped in a FunctionTool
    2. When called, it runs the nested agent
    3. The nested agent's output is returned to the caller
    4. The nested agent runs in isolation (doesn't see parent conversation)
    Agent Tool Configuration
    Python
    Agent Tool Streaming
    Python

    Shell Tools

    Local Shell Tool

    Execute shell commands:

    Python

    Security Considerations:

    • Shell tools are powerful and potentially dangerous
    • Use with appropriate guardrails
    • Consider sandboxing
    • Require approval for sensitive commands
    Shell Tool Configuration
    Python

    Computer Tools

    Computer Interaction

    Tools for interacting with a computer environment:

    Python

    Computer Tool Capabilities:

    • Take screenshots
    • Click buttons
    • Type text
    • Navigate UI
    • Execute computer actions

    Custom Tools

    Custom Tool Implementation

    Create custom tool implementations:

    Python
    Custom Tool with Schema
    Python

    Tool Guardrails

    Tool Input Guardrails

    Validate tool inputs:

    Python
    Tool Output Guardrails

    Validate tool outputs:

    Python

    Tool Metadata

    Tool Origin

    Track where a tool came from:

    Python

    Tool Origin Types:

    • FUNCTION - Regular function tool
    • MCP - MCP server tool
    • AGENT_AS_TOOL - Agent exposed as tool
    Tool Identity

    Tools have unique identities for tracking:

    Python

    Tool Execution Flow

    Complete Tool Execution Flow
    Python

    Tool Use Behavior

    Agent-Level Tool Use Behavior

    Configure how tool results are handled:

    Python
    Custom Tool Use Behavior
    Python

    Tool Timeout

    Setting Tool Timeouts
    Python

    Timeout Behavior:

    • When a timeout occurs, a ToolTimeoutError is raised
    • The error is formatted and sent to the LLM
    • The LLM can retry with different parameters

    Tool Best Practices

    1. Clear Names

    Use descriptive tool names:

    Python
    2. Type Hints

    Always use type hints:

    Python
    3. Docstrings

    Write clear docstrings:

    Python
    4. Error Handling

    Handle errors gracefully:

    Python
    5. Input Validation

    Validate inputs:

    Python

    Common Tool Patterns

    1. Database Query Tool
    Python
    2. API Integration Tool
    Python
    3. File Operations Tool
    Python
    4. Data Processing Tool
    Python

    Summary

    The Tool system is what gives agents their capabilities. Key takeaways:

    1. Function Tools are Python functions decorated with @function_tool
    2. Tool schemas are automatically generated from function signatures
    3. Context can be accessed via RunContextWrapper or ToolContext
    4. Namespaces organize tools and prevent name collisions
    5. Dynamic enablement allows context-dependent tool availability
    6. Hosted tools are OpenAI-provided tools (file search, web search, etc.)
    7. MCP tools come from Model Context Protocol servers
    8. Agents as tools enable powerful multi-agent patterns
    9. Shell tools execute commands
    10. Computer tools interact with computer environments
    11. Custom tools allow custom implementations
    12. Tool guardrails validate inputs and outputs
    13. Tool metadata tracks tool origin and identity
    14. Tool use behavior configures how results are handled
    15. Timeouts prevent hanging tools
    16. Error handling should be graceful
    17. Type hints are essential for schema generation
    18. Docstrings become tool descriptions
    19. Input validation prevents errors
    20. Parallel execution improves performance

    Understanding tools is crucial for building capable agents that can actually do things.