What are Tools?

Before running the examples:

pip install agno openai
export OPENAI_API_KEY="your-api-key"

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.

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

Tool Execution

The execution flow:

1. The agent sends the model its context and available tool definitions.
2. The model returns a response or requests one or more tool calls.
3. Agno validates the arguments and executes each requested tool.
4. Tool results are added to the model context.
5. 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.

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

Control Tool Execution

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.

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.

Next Steps