Add custom_metadata property to all tool types

[hayescode]

This pull request adds support for attaching optional custom metadata to all tool classes in src/agents/tool.py. This metadata can be used to store arbitrary information relevant to each tool instance and is accessible during tool execution, including via agent hooks. Comprehensive tests are included to verify default behavior, metadata assignment, and propagation to hooks.

Why?:

• Developers can add custom attributes to the defined tools that are custom to their implementation.
• For example in our architecture we define things like DisplayName and Icon in our tools for use in our Frontend. Here's what I'm doing today vs. after this PR is merged.

Current

from agents.tool import function_tool
from typing import Optional, Literal, Union, TypeAlias

MarkdownLanguage: TypeAlias = Literal["python","sql","bash","json","markdown","text"]

class ToolMetadata(BaseModel):
    type: str
    default_open: bool = False
    input_language: Union[bool, MarkdownLanguage] = "json"
    output_language: MarkdownLanguage = "text"
    input_parameters: list[str] | None = None
    avatar: Optional[str] = None

    def apply_to_tool(self, tool: Tool, access_token: str | None = None) -> Tool:
        """Apply validated metadata to a tool instance (mutates in place)."""
        if access_token and isinstance(tool, HostedMCPTool):
            tool.tool_config.authorization = access_token
        
        for field_name in self.__class__.model_fields:
            value = getattr(self, field_name)
            if value is not None:
                setattr(tool, field_name, value)
        
        return tool

@function_tool
async def multiply_by_two(x: int) -> int:
    return x * 2

metadata = ToolMetadata(
    display_name="Math Tool",
    family="computation",
    avatar="calculator",
    input_language="python"
)
math_tool = metadata.apply_to_tool(multiply_by_two)
print(f"Configured Tool: {math_tool}")
print(f"Display Name: {math_tool.display_name}")

New

class ToolMetadata(TypedDict):
    type: str
    default_open: bool = False
    input_language: Union[bool, MarkdownLanguage] = "json"
    output_language: MarkdownLanguage = "text"
    input_parameters: list[str] | None = None
    avatar: Optional[str] = None

metadata = ToolMetadata(
    display_name="Math Tool",
    family="computation",
    avatar="calculator",
    input_language="python"
)

@function_tool(custom_metadata=metadata)
async def multiply_by_two(x: int) -> int:
    return x * 2

Custom metadata support for tools:

• Added a custom_metadata field to all tool classes (FunctionTool, FileSearchTool, WebSearchTool, ComputerTool, HostedMCPTool, CodeInterpreterTool, ImageGenerationTool, LocalShellTool) in src/agents/tool.py, allowing arbitrary metadata to be attached to each tool instance. [1] [2] [3] [4] [5] [6] [7] [8]

Testing and validation:

• Added tests/test_tool_custom_metadata.py with tests to ensure that custom_metadata defaults to None, can be set, and is available in agent hooks during tool execution.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[seratch]

Thanks for sharing this idea! However, we'd like to hold off adding this option to the core module at this moment. Your current approach looks more explicit and it should work well. So, please start with your own module for now.

EDITED: sorry my original sentence was unclear