0
# Tools
1

2
Tools enable agents to perform actions beyond text generation. The SDK supports function tools (Python functions), hosted tools (OpenAI-provided capabilities), shell tools, MCP tools, and custom tool implementations with guardrails and error handling.
3

4
## Capabilities
5

6
### Tool Union Type
7

8
```python { .api }
9
Tool = Union[
10
    FunctionTool,
11
    FileSearchTool,
12
    WebSearchTool,
13
    ComputerTool,
14
    HostedMCPTool,
15
    ShellTool,
16
    ApplyPatchTool,
17
    LocalShellTool,
18
    ImageGenerationTool,
19
    CodeInterpreterTool
20
]
21
```
22

23
Union of all supported tool types.
24

25
### Function Tools
26

27
Python functions wrapped as agent tools with automatic schema generation.
28

29
```python { .api }
30
class FunctionTool:
31
    """
32
    Tool wrapping a Python function.
33

34
    Attributes:
35
    - name: str - Tool name (derived from function name)
36
    - description: str - Tool description (from docstring)
37
    - params_json_schema: dict[str, Any] - Parameter JSON schema
38
    - on_invoke_tool: Callable - Function to invoke
39
    - strict_json_schema: bool - Use strict mode
40
    - is_enabled: bool | Callable - Tool enabled state
41
    - tool_input_guardrails: list[ToolInputGuardrail] | None - Input guardrails
42
    - tool_output_guardrails: list[ToolOutputGuardrail] | None - Output guardrails
43
    """
44

45
def function_tool(
46
    func: ToolFunction | None = None,
47
    *,
48
    name_override: str | None = None,
49
    description_override: str | None = None,
50
    docstring_style: DocstringStyle | None = None,
51
    use_docstring_info: bool = True,
52
    failure_error_function: ToolErrorFunction | None = None,
53
    strict_mode: bool = True,
54
    is_enabled: bool | Callable = True
55
):
56
    """
57
    Decorator to create FunctionTool from function.
58

59
    Parameters:
60
    - func: Function to wrap (when used as @function_tool())
61
    - name_override: Custom tool name
62
    - description_override: Custom description
63
    - docstring_style: Docstring parsing style
64
    - use_docstring_info: Extract info from docstring
65
    - failure_error_function: Custom error handler
66
    - strict_mode: Enable strict JSON schema
67
    - is_enabled: Tool enabled state or function
68

69
    Returns:
70
    - FunctionTool or decorator
71
    """
72

73
class FunctionToolResult:
74
    """
75
    Result of function tool execution.
76

77
    Attributes:
78
    - tool: FunctionTool - The tool that was executed
79
    - output: Any - Tool output value
80
    - run_item: RunItem - Associated run item
81
    """
82
```
83

84
Usage example:
85

86
```python
87
from agents import Agent, function_tool
88

89
@function_tool
90
def get_weather(city: str, units: str = "celsius") -> str:
91
    """
92
    Get the weather for a city.
93

94
    Args:
95
        city: The city name
96
        units: Temperature units (celsius or fahrenheit)
97

98
    Returns:
99
        Weather information as a string
100
    """
101
    # Implementation
102
    return f"Weather in {city}: 22°{units[0].upper()}"
103

104
@function_tool(
105
    name_override="search_db",
106
    description_override="Search the knowledge database",
107
    strict_mode=True
108
)
109
def search_knowledge_base(query: str) -> dict:
110
    """Search for information."""
111
    return {"results": [...]}
112

113
# Conditional tool enabling
114
def should_enable_tool(ctx):
115
    return ctx.context.user.is_premium
116

117
@function_tool(is_enabled=should_enable_tool)
118
def premium_feature():
119
    """Premium-only feature."""
120
    ...
121

122
agent = Agent(
123
    name="Assistant",
124
    tools=[get_weather, search_knowledge_base, premium_feature]
125
)
126
```
127

128
### File Search Tool
129

130
Hosted tool for searching vector stores with file content.
131

132
```python { .api }
133
class FileSearchTool:
134
    """
135
    Hosted tool for vector store search.
136

137
    Attributes:
138
    - vector_store_ids: list[str] - Vector store IDs to search
139
    - max_num_results: int | None - Maximum number of results
140
    - include_search_results: bool - Include results in output
141
    - ranking_options: RankingOptions | None - Ranking configuration
142
    - filters: Filters | None - Search filters
143

144
    Properties:
145
    - name: Returns "file_search"
146
    """
147
```
148

149
Usage example:
150

151
```python
152
from agents import Agent, FileSearchTool
153

154
file_search = FileSearchTool(
155
    vector_store_ids=["vs_123", "vs_456"],
156
    max_num_results=10,
157
    include_search_results=True
158
)
159

160
agent = Agent(
161
    name="Knowledge Agent",
162
    instructions="Use file search to answer questions.",
163
    tools=[file_search]
164
)
165
```
166

167
### Web Search Tool
168

169
Hosted tool for web search capabilities.
170

171
```python { .api }
172
class WebSearchTool:
173
    """
174
    Hosted tool for web search.
175

176
    Attributes:
177
    - user_location: UserLocation | None - User location for results
178
    - filters: WebSearchToolFilters | None - Search filters
179
    - search_context_size: Literal["low", "medium", "high"] - Context amount
180

181
    Properties:
182
    - name: Returns "web_search"
183
    """
184
```
185

186
Usage example:
187

188
```python
189
from agents import Agent, WebSearchTool
190

191
web_search = WebSearchTool(
192
    search_context_size="high",
193
    filters={
194
        "recency": "recent",
195
        "max_results": 5
196
    }
197
)
198

199
agent = Agent(
200
    name="Research Agent",
201
    instructions="Search the web for current information.",
202
    tools=[web_search]
203
)
204
```
205

206
### Computer Tool
207

208
Hosted tool for computer control (UI automation).
209

210
```python { .api }
211
class ComputerTool:
212
    """
213
    Hosted tool for computer control.
214

215
    Attributes:
216
    - computer: Computer | AsyncComputer - Computer implementation
217
    - on_safety_check: Callable | None - Safety check callback
218

219
    Properties:
220
    - name: Returns "computer_use_preview"
221
    """
222

223
class ComputerToolSafetyCheckData:
224
    """
225
    Data for computer tool safety checks.
226

227
    Attributes:
228
    - ctx_wrapper: RunContextWrapper - Run context
229
    - agent: Agent - Current agent
230
    - tool_call: ToolCall - The tool call
231
    - safety_check: SafetyCheck - Safety check details
232
    """
233
```
234

235
Usage example:
236

237
```python
238
from agents import Agent, ComputerTool, Computer
239

240
class MyComputer(Computer):
241
    @property
242
    def environment(self):
243
        return "ubuntu"
244

245
    @property
246
    def dimensions(self):
247
        return (1920, 1080)
248

249
    def screenshot(self):
250
        # Take screenshot
251
        return "base64_image_data"
252

253
    def click(self, x, y, button="left"):
254
        # Click at position
255
        ...
256

257
    # Implement other methods...
258

259
async def safety_check(data):
260
    # Review action before execution
261
    print(f"Agent wants to: {data.tool_call}")
262
    return True  # Allow action
263

264
computer_tool = ComputerTool(
265
    computer=MyComputer(),
266
    on_safety_check=safety_check
267
)
268

269
agent = Agent(
270
    name="Automation Agent",
271
    instructions="Control the computer to complete tasks.",
272
    tools=[computer_tool]
273
)
274
```
275

276
### Shell Tool
277

278
Modern shell command execution tool.
279

280
```python { .api }
281
class ShellTool:
282
    """
283
    Next-generation shell tool.
284

285
    Attributes:
286
    - executor: ShellExecutor - Executor function
287
    - name: str - Tool name (default "shell")
288
    """
289

290
class ShellCommandRequest:
291
    """
292
    Modern shell command request.
293

294
    Attributes:
295
    - ctx_wrapper: RunContextWrapper - Run context
296
    - data: ShellCallData - Command data
297
    """
298

299
class ShellResult:
300
    """
301
    Shell execution result.
302

303
    Attributes:
304
    - output: list[ShellCommandOutput] - Command outputs
305
    - max_output_length: int | None - Max output length
306
    - provider_data: dict[str, Any] | None - Provider-specific data
307
    """
308

309
class ShellCommandOutput:
310
    """
311
    Output from single shell command.
312

313
    Attributes:
314
    - stdout: str - Standard output
315
    - stderr: str - Standard error
316
    - outcome: ShellCallOutcome - Terminal condition
317
    - command: str - Executed command
318
    - provider_data: dict[str, Any] | None - Provider data
319

320
    Properties:
321
    - exit_code: int | None - Exit code if available
322
    - status: str - Status string
323
    """
324

325
class ShellCallOutcome:
326
    """
327
    Terminal condition of shell command.
328

329
    Attributes:
330
    - type: str - Outcome type
331
    - exit_code: int | None - Exit code
332
    """
333

334
class ShellCallData:
335
    """
336
    Normalized shell call data.
337

338
    Attributes:
339
    - call_id: str - Call identifier
340
    - action: ShellActionRequest - Action details
341
    - status: str - Call status
342
    - raw: dict - Raw call data
343
    """
344

345
class ShellActionRequest:
346
    """
347
    Shell action payload.
348

349
    Attributes:
350
    - commands: list[str] - Commands to execute
351
    - timeout_ms: int | None - Timeout in milliseconds
352
    - max_output_length: int | None - Maximum output length
353
    """
354
```
355

356
Type alias:
357

358
```python { .api }
359
ShellExecutor = Callable[
360
    [ShellCommandRequest],
361
    MaybeAwaitable[str | ShellResult]
362
]
363
```
364

365
Usage example:
366

367
```python
368
from agents import Agent, ShellTool, ShellCommandRequest, ShellResult
369
import subprocess
370

371
async def execute_shell(request: ShellCommandRequest) -> ShellResult:
372
    outputs = []
373
    for cmd in request.data.action.commands:
374
        result = subprocess.run(
375
            cmd,
376
            shell=True,
377
            capture_output=True,
378
            text=True
379
        )
380
        outputs.append(ShellCommandOutput(
381
            stdout=result.stdout,
382
            stderr=result.stderr,
383
            outcome=ShellCallOutcome(
384
                type="exited",
385
                exit_code=result.returncode
386
            ),
387
            command=cmd,
388
            provider_data=None
389
        ))
390
    return ShellResult(output=outputs, max_output_length=None, provider_data=None)
391

392
shell_tool = ShellTool(executor=execute_shell)
393

394
agent = Agent(
395
    name="DevOps Agent",
396
    instructions="Run shell commands to manage the system.",
397
    tools=[shell_tool]
398
)
399
```
400

401
### Local Shell Tool
402

403
Simple local shell command execution.
404

405
```python { .api }
406
class LocalShellTool:
407
    """
408
    Tool for local shell command execution.
409

410
    Attributes:
411
    - executor: LocalShellExecutor - Executor function
412

413
    Properties:
414
    - name: Returns "local_shell"
415
    """
416

417
class LocalShellCommandRequest:
418
    """
419
    Local shell command request.
420

421
    Attributes:
422
    - ctx_wrapper: RunContextWrapper - Run context
423
    - data: dict - Command data
424
    """
425
```
426

427
Type alias:
428

429
```python { .api }
430
LocalShellExecutor = Callable[
431
    [LocalShellCommandRequest],
432
    MaybeAwaitable[str]
433
]
434
```
435

436
Usage example:
437

438
```python
439
from agents import Agent, LocalShellTool
440
import subprocess
441

442
async def run_local_shell(request):
443
    cmd = request.data["command"]
444
    result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
445
    return f"stdout: {result.stdout}\nstderr: {result.stderr}"
446

447
local_shell = LocalShellTool(executor=run_local_shell)
448

449
agent = Agent(
450
    name="Script Runner",
451
    tools=[local_shell]
452
)
453
```
454

455
### Apply Patch Tool
456

457
Tool for applying diffs to files (code editing).
458

459
```python { .api }
460
class ApplyPatchTool:
461
    """
462
    Hosted apply_patch tool.
463

464
    Attributes:
465
    - editor: ApplyPatchEditor - Editor implementation
466
    - name: str - Tool name (default "apply_patch")
467
    """
468
```
469

470
Editor protocol:
471

472
```python { .api }
473
class ApplyPatchEditor:
474
    """Protocol for editor implementation."""
475

476
    def create_file(operation: ApplyPatchOperation) -> MaybeAwaitable[ApplyPatchResult | str | None]:
477
        """Create a new file."""
478

479
    def update_file(operation: ApplyPatchOperation) -> MaybeAwaitable[ApplyPatchResult | str | None]:
480
        """Update existing file."""
481

482
    def delete_file(operation: ApplyPatchOperation) -> MaybeAwaitable[ApplyPatchResult | str | None]:
483
        """Delete a file."""
484

485
class ApplyPatchOperation:
486
    """
487
    Single apply_patch operation.
488

489
    Attributes:
490
    - type: ApplyPatchOperationType - Operation type
491
    - path: str - File path
492
    - diff: str | None - Diff content
493
    """
494

495
class ApplyPatchResult:
496
    """
497
    Result of editor operation.
498

499
    Attributes:
500
    - status: Literal["completed", "failed"] | None - Operation status
501
    - output: str | None - Operation output
502
    """
503
```
504

505
Usage example:
506

507
```python
508
from agents import Agent, ApplyPatchTool, ApplyPatchEditor, ApplyPatchOperation
509

510
class MyEditor(ApplyPatchEditor):
511
    def create_file(self, op):
512
        # Create file at op.path with op.diff
513
        return ApplyPatchResult(status="completed", output="File created")
514

515
    def update_file(self, op):
516
        # Apply diff to existing file
517
        return ApplyPatchResult(status="completed", output="File updated")
518

519
    def delete_file(self, op):
520
        # Delete file
521
        return ApplyPatchResult(status="completed", output="File deleted")
522

523
apply_patch = ApplyPatchTool(editor=MyEditor())
524

525
agent = Agent(
526
    name="Code Editor Agent",
527
    instructions="Edit code files as requested.",
528
    tools=[apply_patch]
529
)
530
```
531

532
### Hosted MCP Tool
533

534
Tool for accessing hosted MCP servers.
535

536
```python { .api }
537
class HostedMCPTool:
538
    """
539
    Hosted MCP server tool.
540

541
    Attributes:
542
    - tool_config: Mcp - MCP configuration
543
    - on_approval_request: MCPToolApprovalFunction | None - Approval handler
544

545
    Properties:
546
    - name: Returns "hosted_mcp"
547
    """
548

549
class MCPToolApprovalRequest:
550
    """
551
    MCP tool approval request.
552

553
    Attributes:
554
    - ctx_wrapper: RunContextWrapper - Run context
555
    - data: dict - Approval data
556
    """
557

558
class MCPToolApprovalFunctionResult:
559
    """
560
    Result of MCP approval function.
561

562
    Attributes:
563
    - approve: bool - Whether to approve
564
    - reason: str | None - Optional reason
565
    """
566
```
567

568
Type alias:
569

570
```python { .api }
571
MCPToolApprovalFunction = Callable[
572
    [MCPToolApprovalRequest],
573
    MaybeAwaitable[MCPToolApprovalFunctionResult]
574
]
575
```
576

577
Usage example:
578

579
```python
580
from agents import Agent, HostedMCPTool
581

582
async def approve_mcp_action(request):
583
    # Review MCP action
584
    if "dangerous" in request.data.get("action", ""):
585
        return {"approve": False, "reason": "Potentially dangerous"}
586
    return {"approve": True}
587

588
hosted_mcp = HostedMCPTool(
589
    tool_config={"server": "mcp_server_id"},
590
    on_approval_request=approve_mcp_action
591
)
592

593
agent = Agent(
594
    name="MCP Agent",
595
    tools=[hosted_mcp]
596
)
597
```
598

599
### Code Interpreter Tool
600

601
Hosted tool for code execution.
602

603
```python { .api }
604
class CodeInterpreterTool:
605
    """
606
    Hosted code interpreter tool.
607

608
    Attributes:
609
    - tool_config: CodeInterpreter - Configuration
610

611
    Properties:
612
    - name: Returns "code_interpreter"
613
    """
614
```
615

616
Usage example:
617

618
```python
619
from agents import Agent, CodeInterpreterTool
620

621
code_interpreter = CodeInterpreterTool(
622
    tool_config={"runtime": "python3"}
623
)
624

625
agent = Agent(
626
    name="Data Analysis Agent",
627
    instructions="Analyze data using Python code.",
628
    tools=[code_interpreter]
629
)
630
```
631

632
### Image Generation Tool
633

634
Hosted tool for generating images.
635

636
```python { .api }
637
class ImageGenerationTool:
638
    """
639
    Hosted image generation tool.
640

641
    Attributes:
642
    - tool_config: ImageGeneration - Configuration
643

644
    Properties:
645
    - name: Returns "image_generation"
646
    """
647
```
648

649
Usage example:
650

651
```python
652
from agents import Agent, ImageGenerationTool
653

654
image_gen = ImageGenerationTool(
655
    tool_config={
656
        "model": "dall-e-3",
657
        "quality": "hd"
658
    }
659
)
660

661
agent = Agent(
662
    name="Creative Agent",
663
    instructions="Generate images based on descriptions.",
664
    tools=[image_gen]
665
)
666
```
667

668
### Tool Output Types
669

670
Structured output types for tools.
671

672
```python { .api }
673
class ToolOutputText:
674
    """
675
    Text tool output.
676

677
    Attributes:
678
    - type: Literal["text"]
679
    - text: str - Text content
680
    """
681

682
class ToolOutputTextDict:
683
    """
684
    TypedDict variant for text output.
685

686
    Attributes:
687
    - type: Literal["text"]
688
    - text: str
689
    """
690

691
class ToolOutputImage:
692
    """
693
    Image tool output.
694

695
    Attributes:
696
    - type: Literal["image"]
697
    - image_url: str | None - Image URL
698
    - file_id: str | None - File ID
699
    - detail: str | None - Detail level
700
    """
701

702
class ToolOutputImageDict:
703
    """
704
    TypedDict variant for image output.
705

706
    Attributes:
707
    - type: Literal["image"]
708
    - image_url: str | None
709
    - file_id: str | None
710
    - detail: str | None
711
    """
712

713
class ToolOutputFileContent:
714
    """
715
    File content tool output.
716

717
    Attributes:
718
    - type: Literal["file"]
719
    - file_data: str | None - Base64 file data
720
    - file_url: str | None - File URL
721
    - file_id: str | None - File ID
722
    - filename: str | None - Filename
723
    """
724

725
class ToolOutputFileContentDict:
726
    """
727
    TypedDict variant for file output.
728

729
    Attributes:
730
    - type: Literal["file"]
731
    - file_data: str | None
732
    - file_url: str | None
733
    - file_id: str | None
734
    - filename: str | None
735
    """
736
```
737

738
Usage example:
739

740
```python
741
from agents import function_tool, ToolOutputImage
742

743
@function_tool
744
def generate_chart(data: list[float]) -> ToolOutputImage:
745
    """Generate a chart from data."""
746
    # Create chart
747
    chart_url = "https://example.com/chart.png"
748
    return ToolOutputImage(
749
        type="image",
750
        image_url=chart_url,
751
        detail="high"
752
    )
753
```
754

755
### Tool Error Handling
756

757
Error handling for tool failures.
758

759
```python { .api }
760
def default_tool_error_function(ctx: RunContextWrapper, error: Exception) -> str:
761
    """
762
    Default error handler for tool failures.
763

764
    Parameters:
765
    - ctx: Run context
766
    - error: Exception that occurred
767

768
    Returns:
769
    - str: Error message for the LLM
770
    """
771
```
772

773
Type alias:
774

775
```python { .api }
776
ToolErrorFunction = Callable[
777
    [RunContextWrapper, Exception],
778
    MaybeAwaitable[str]
779
]
780
```
781

782
Usage example:
783

784
```python
785
from agents import function_tool
786

787
async def custom_error_handler(ctx, error):
788
    # Log error
789
    print(f"Tool error: {error}")
790
    # Return user-friendly message
791
    return "The tool encountered an error. Please try again."
792

793
@function_tool(failure_error_function=custom_error_handler)
794
def risky_operation(input: str) -> str:
795
    """An operation that might fail."""
796
    # Potentially failing code
797
    ...
798
```
799

800
## Computer Control Interface
801

802
Abstract interfaces for computer control implementations used with ComputerTool.
803

804
### Synchronous Computer
805

806
```python { .api }
807
class Computer:
808
    """Synchronous computer control interface."""
809

810
    @property
811
    def environment(self) -> Environment:
812
        """
813
        Get environment type.
814

815
        Returns:
816
        - Environment: One of "mac", "windows", "ubuntu", "browser"
817
        """
818

819
    @property
820
    def dimensions(self) -> tuple[int, int]:
821
        """
822
        Get screen dimensions.
823

824
        Returns:
825
        - tuple[int, int]: Width and height in pixels
826
        """
827

828
    def screenshot() -> str:
829
        """
830
        Take screenshot.
831

832
        Returns:
833
        - str: Base64-encoded image
834
        """
835

836
    def click(x: int, y: int, button: Button = "left") -> None:
837
        """
838
        Click at position.
839

840
        Parameters:
841
        - x: X coordinate
842
        - y: Y coordinate
843
        - button: Mouse button ("left", "right", "wheel", "back", "forward")
844
        """
845

846
    def double_click(x: int, y: int) -> None:
847
        """
848
        Double click at position.
849

850
        Parameters:
851
        - x: X coordinate
852
        - y: Y coordinate
853
        """
854

855
    def scroll(x: int, y: int, scroll_x: int, scroll_y: int) -> None:
856
        """
857
        Scroll at position.
858

859
        Parameters:
860
        - x: X coordinate
861
        - y: Y coordinate
862
        - scroll_x: Horizontal scroll amount
863
        - scroll_y: Vertical scroll amount
864
        """
865

866
    def type(text: str) -> None:
867
        """
868
        Type text.
869

870
        Parameters:
871
        - text: Text to type
872
        """
873

874
    def wait() -> None:
875
        """Wait for UI updates."""
876

877
    def move(x: int, y: int) -> None:
878
        """
879
        Move cursor.
880

881
        Parameters:
882
        - x: X coordinate
883
        - y: Y coordinate
884
        """
885

886
    def keypress(keys: str) -> None:
887
        """
888
        Press keys.
889

890
        Parameters:
891
        - keys: Keys to press (e.g., "ctrl+c")
892
        """
893

894
    def drag(path: list[tuple[int, int]]) -> None:
895
        """
896
        Drag along path.
897

898
        Parameters:
899
        - path: List of (x, y) coordinates
900
        """
901
```
902

903
### Asynchronous Computer
904

905
```python { .api }
906
class AsyncComputer:
907
    """Asynchronous computer control interface."""
908

909
    @property
910
    def environment(self) -> Environment:
911
        """Get environment type."""
912

913
    @property
914
    def dimensions(self) -> tuple[int, int]:
915
        """Get screen dimensions."""
916

917
    async def screenshot() -> str:
918
        """Take screenshot."""
919

920
    async def click(x: int, y: int, button: Button = "left") -> None:
921
        """Click at position."""
922

923
    async def double_click(x: int, y: int) -> None:
924
        """Double click at position."""
925

926
    async def scroll(x: int, y: int, scroll_x: int, scroll_y: int) -> None:
927
        """Scroll at position."""
928

929
    async def type(text: str) -> None:
930
        """Type text."""
931

932
    async def wait() -> None:
933
        """Wait for UI updates."""
934

935
    async def move(x: int, y: int) -> None:
936
        """Move cursor."""
937

938
    async def keypress(keys: str) -> None:
939
        """Press keys."""
940

941
    async def drag(path: list[tuple[int, int]]) -> None:
942
        """Drag along path."""
943
```
944

945
### Type Definitions
946

947
```python { .api }
948
Environment = Literal["mac", "windows", "ubuntu", "browser"]
949

950
Button = Literal["left", "right", "wheel", "back", "forward"]
951
```
952