Tools

Give agents typed callable actions for APIs, code execution, search, and provider-hosted capabilities.

Tools give your agent the ability to take actions: call an API, run code, or search the web. The agent decides when to call a tool based on the conversation, runs it, then loops back with the result until it has a final answer.

Custom tools

Define a tool with the @tool decorator. The SDK reads your type hints and docstring to build the JSON schema the model uses to call it correctly.

from agnt5 import Agent
from agnt5.context import Context
from agnt5.tool import tool

@tool
async def get_weather(ctx: Context, city: str) -> str:
    """Get the current weather for a city.

    Args:
        city: Name of the city to check.
    """
    # call your weather API here
    return f"Sunny, 22°C in {city}"

agent = Agent(
    name="assistant",
    model="openai/gpt-4o-mini",
    instructions="You help users with weather queries.",
    tools=[get_weather],
)

result = await agent.run("What is the weather in Paris?")
print(result.output)

Things to know

The first parameter must be ctx: Context (injected automatically, not exposed to the model).
Every other parameter becomes a field the model can fill in. Type hints (str, int, bool, list) and docstring Args: descriptions are used to build the schema.
Sync functions are wrapped in a thread pool automatically.
The tool is registered globally at import time and can be reused across agents.

@tool decorator options:

Parameter	Type	Default	Description
`name`	`str`	function’s `__name__`	How the tool appears to the model
`description`	`str`	first line of docstring	What the model reads to decide when to call this tool
`confirmation`	`bool`	`False`	Reserved for future human-approval flow

Inspecting tool calls

After agent.run(), result.tool_calls lists every tool the agent invoked during its loop.

result = await agent.run("What is the weather in Paris?")

print(result.output)      # final answer
print(result.tool_calls)  # [{"name": "get_weather", "arguments": '{"city": "Paris"}', "iteration": 1}]

Agents as tools

Pass another Agent directly in the tools list. The SDK wraps it automatically. The calling agent invokes it like any other tool and gets the specialist’s response back before continuing its own reasoning.

from agnt5 import Agent

lookup_agent = Agent(
    name="lookup",
    model="openai/gpt-4o-mini",
    instructions="You look up factual information and return concise answers.",
)

orchestrator = Agent(
    name="orchestrator",
    model="openai/gpt-4o-mini",
    instructions="Use lookup to find information, then summarize it for the user.",
    tools=[lookup_agent],   # auto-wrapped as ask_lookup
)

result = await orchestrator.run("What is the capital of Japan?")
print(result.output)

Sandbox tools

sandbox_tools() returns four ready-made tools that give your agent a persistent code execution workspace. The sandbox state is shared across all tool calls within a single agent run. The agent can write a file, run it, and read the output in sequence.

from agnt5 import Agent, sandbox_tools

agent = Agent(
    name="coder",
    model="openai/gpt-4o-mini",
    instructions=(
        "You are a coding assistant. Use sandbox_execute_code to run code, "
        "sandbox_write_file to save files, and sandbox_read_file to inspect results. "
        "Always verify your code works by running it before returning the answer."
    ),
    tools=sandbox_tools(),
)

result = await agent.run("Calculate the first 10 fibonacci numbers in Python")
print(result.output)

The four tools:

Tool	What it does
`sandbox_execute_code`	Run code and return stdout, stderr, and exit code. Supports `python`, `javascript`, and `bash`
`sandbox_write_file`	Write a file to the sandbox workspace
`sandbox_read_file`	Read a file from the sandbox workspace
`sandbox_list_files`	List files in the workspace, optionally recursive

Built-in tools

Built-in tools run entirely on the provider’s infrastructure. You enable them and the provider handles execution. Results are already included in the model’s response; no local code runs.

from agnt5 import Agent
from agnt5.lm import BuiltInTool

agent = Agent(
    name="researcher",
    model="openai/gpt-4o-mini",
    instructions=(
        "You are a research assistant. Always use web_search to find current "
        "information, never answer from training knowledge alone."
    ),
    built_in_tools=[BuiltInTool.WEB_SEARCH],
)

result = await agent.run("Who won the most recent Formula 1 championship?")
print(result.output)

Available built-in tools:

Tool	What it does	Provider
`BuiltInTool.WEB_SEARCH`	Live web search with cited results	OpenAI, Anthropic
`BuiltInTool.CODE_INTERPRETER`	Run code in a provider-hosted sandbox	OpenAI only
`BuiltInTool.FILE_SEARCH`	Search over files uploaded to the provider	OpenAI only
`BuiltInTool.WEB_FETCH`	Fetch the content of a specific URL	Anthropic only

You can mix built-in tools with custom tools on the same agent:

from agnt5 import Agent, sandbox_tools
from agnt5.lm import BuiltInTool

agent = Agent(
    name="assistant",
    model="openai/gpt-4o-mini",
    instructions="Search the web for information and run code when needed.",
    built_in_tools=[BuiltInTool.WEB_SEARCH],
    tools=sandbox_tools(),
)

MCP tools

Use Model Context Protocol when a tool already exists in an external MCP server. MCPClient connects to the server, discovers tools, and returns AGNT5 Tool objects that you pass to an agent.

from agnt5 import Agent
from agnt5.mcp import MCPClient

mcp = MCPClient(id="repo-tools")
mcp.add_streamable_http_server("deepwiki", "https://mcp.deepwiki.com/mcp")
await mcp.connect()

agent = Agent(
    name="repository_researcher",
    model="openai/gpt-4o-mini",
    instructions="Use available tools to answer questions about code repositories.",
    tools=mcp.get_tools(),
)

See Model Context Protocol for transports, direct tool calls, and exposing AGNT5 primitives as an MCP server.

Human-in-the-loop tools

Two built-in tool classes let an agent pause and wait for a human response before continuing. Both require a workflow context because execution must durably suspend while waiting.

from agnt5 import Agent, workflow, WorkflowContext
from agnt5.tool import AskUserTool, RequestApprovalTool

@workflow
async def agent_with_hitl(ctx: WorkflowContext, task: str) -> dict:
    agent = Agent(
        name="assistant",
        model="openai/gpt-4o-mini",
        instructions=(
            "Ask the user for clarification when the request is ambiguous. "
            "Always request approval before making any changes."
        ),
        tools=[AskUserTool(ctx), RequestApprovalTool(ctx)],
    )
    result = await agent.run(task, context=ctx)
    return {"response": result.output}

Tool	Behaviour
`AskUserTool(ctx)`	Agent calls `ask_user` with a question. Workflow pauses until the user types a response
`RequestApprovalTool(ctx)`	Agent calls `request_approval` with an action description. Workflow pauses and shows Approve / Reject to the user