What are Tools?

Agents use tools to take actions, like looking up records, calling APIs, updating systems, and completing work for users. Add a Python function or toolkit to tools, and the model can select it when a request requires it.

order_agent.py

from agno.agent import Agent
from agno.models.openai import OpenAIResponses


def lookup_order(order_id: str) -> dict:
    """Return the status and delivery date for an order.

    Args:
        order_id: The order ID to look up.
    """
    return {
        "order_id": order_id,
        "status": "shipped",
        "delivery_date": "2026-07-22",
    }


agent = Agent(
    model=OpenAIResponses(id="gpt-5.4-mini"),
    tools=[lookup_order],
    instructions="Use the order tool when a customer asks about a delivery.",
)

agent.print_response("When will order ORD-123 arrive?")

Agno builds a tool definition from the function name, docstring, and type hints. The model receives that definition, chooses the tool and arguments, then uses the result to produce its response.

Choose a Tool Source

Use case	Tool source
Call application code or an internal API	Python function
Add a packaged integration with related operations	Toolkit
Connect to a service exposed through Model Context Protocol	MCPTools
Give an agent a compact interface to a complex external system	Context Provider
Select tools for each user or session at run time	Callable factory

Tool Execution

The execution flow:

The agent sends the model its context and available tool definitions.
The model returns a response or requests one or more tool calls.
Agno validates the arguments and executes each requested tool.
Tool results are added to the model context.
The loop continues until the model returns a final response.

When a model requests multiple tool calls, arun() and aprint_response() can execute them concurrently. The selected model must support parallel tool calls.

Design Tools for Reliable Calls

The model uses the tool schema to decide when and how to call a function.

Practice	Why it matters
Use a specific function name	Helps the model select the correct operation
Write a concise docstring	Explains when the tool should be used
Add type hints and argument descriptions	Produces a precise input schema
Expose only the tools needed for the task	Reduces ambiguous choices and limits access
Return structured, relevant results	Gives the model useful context for its response

Use include_tools and exclude_tools to limit operations exposed by a toolkit. See Including and Excluding Tools.

Control Tool Execution

Requirement	Configuration
Limit calls during one run	Set `tool_call_limit`
Review a sensitive action	Mark the tool with `requires_confirmation=True`
Collect missing fields from a user	Use `requires_user_input=True`
Execute an operation in your application	Use `external_execution=True`
Handle failures from custom tools	Configure tool exceptions

Runs with human-in-the-loop requirements pause until your application resolves the active requirement and continues the run.

Tool Built-in Parameters

Agno strips built-in parameters from the schema sent to the model and injects them when the tool runs.

Parameter	Use
`run_context`	Access the current user, session state, dependencies, metadata, and knowledge filters
`agent`	Access the active Agent from an agent tool
`team`	Access the active Team from a team tool
`images`, `videos`, `audios`, `files`	Access media attached to the run

Access Run Context

Add a run_context: RunContext parameter when a tool needs the current user, session state, dependencies, metadata, or knowledge filters. Agno injects the value at execution time and omits it from the schema sent to the model.

from agno.run import RunContext


def add_item(run_context: RunContext, item: str) -> str:
    """Add an item to the current session's shopping list."""
    if run_context.session_state is None:
        run_context.session_state = {}
    shopping_list = run_context.session_state.setdefault("shopping_list", [])
    shopping_list.append(item)
    return f"Shopping list: {shopping_list}"

See the RunContext reference and State Management.

Return Tool Results

Functions can return strings, numbers, dictionaries, lists, and other serializable values. Use ToolResult when a tool needs to return media or files alongside text.

Parameter	Type	Default	Description
`content`	`str`	Required	Main text content/output from the tool
`images`	`Optional[List[Image]]`	`None`	Generated image artifacts
`videos`	`Optional[List[Video]]`	`None`	Generated video artifacts
`audios`	`Optional[List[Audio]]`	`None`	Generated audio artifacts

Next Steps

Agent Tools

Add functions and toolkits to an agent.

Available Toolkits

Browse integrations by data source and operation.

Create Tools

Build Python functions and reusable toolkits.

MCP Tools

Connect agents to Model Context Protocol servers.

Update Tools

Add or replace tools after initialization.

Tool Hooks

Run logic before and after tool calls.

Get Started

Basics

Advanced

Production

Providers

Other

Additional Resources

What are Tools?

Choose a Tool Source

Tool Execution

Design Tools for Reliable Calls

Control Tool Execution

Tool Built-in Parameters

Access Run Context

Return Tool Results

Next Steps

Agent Tools

Available Toolkits

Create Tools

MCP Tools

Update Tools

Tool Hooks

​Choose a Tool Source

​Tool Execution

​Design Tools for Reliable Calls

​Control Tool Execution

​Tool Built-in Parameters

​Access Run Context

​Return Tool Results

​Next Steps

Agent Tools

Available Toolkits

Create Tools

MCP Tools

Update Tools

Tool Hooks

Choose a Tool Source

Tool Execution

Design Tools for Reliable Calls

Control Tool Execution

Tool Built-in Parameters

Access Run Context

Return Tool Results

Next Steps