Building Agents

To build effective agents, start simple: a model, tools, and instructions. Once that works, layer in more functionality as needed. For example, here's the simplest possible agent with access to HackerNews:

hackernews_agent.py

from agno.agent import Agent
from agno.models.anthropic import Claude
from agno.tools.hackernews import HackerNewsTools

agent = Agent(
    model=Claude(id="claude-sonnet-4-5"),
    tools=[HackerNewsTools()],
    instructions="Write a report on the topic. Output only the report.",
    markdown=True,
)
agent.print_response("Trending startups and products.", stream=True)

Before you run

Create and activate a Python virtual environment. Install agno and anthropic, then set ANTHROPIC_API_KEY:

uv pip install -U agno anthropic
export ANTHROPIC_API_KEY="your-anthropic-api-key"
python hackernews_agent.py

On Windows PowerShell, use $Env:ANTHROPIC_API_KEY="your-anthropic-api-key".

Run your Agent

Use Agent.print_response() for development. It prints the response in a readable format in your terminal.

For production, use Agent.run() or Agent.arun():

from typing import Iterator
from agno.agent import Agent, RunOutputEvent, RunEvent
from agno.models.anthropic import Claude
from agno.tools.hackernews import HackerNewsTools

agent = Agent(
    model=Claude(id="claude-sonnet-4-5"),
    tools=[HackerNewsTools()],
    instructions="Write a report on the topic. Output only the report.",
    markdown=True,
)

# Stream the response
stream: Iterator[RunOutputEvent] = agent.run("Trending products", stream=True)
for chunk in stream:
    if chunk.event == RunEvent.run_content and chunk.content:
        print(chunk.content)

Callable Factories

Pass a function instead of a static list for tools or knowledge. The factory is resolved for each run, using its cached result when caching is enabled. This lets the toolset or knowledge base vary per user or session.

callable_tools.py

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.run import RunContext
from agno.tools.duckduckgo import DuckDuckGoTools
from agno.tools.yfinance import YFinanceTools


def get_tools(run_context: RunContext):
    role = (run_context.session_state or {}).get("role", "general")
    if role == "finance":
        return [YFinanceTools()]
    return [DuckDuckGoTools()]


agent = Agent(
    model=OpenAIResponses(id="gpt-5-mini"),
    tools=get_tools,
    cache_callables=False,
)

agent.print_response("AAPL stock price?", session_state={"role": "finance"}, stream=True)
agent.print_response("Latest AI news?", session_state={"role": "general"}, stream=True)

To run callable_tools.py in the same environment, install the additional tools and configure OpenAI:

uv pip install -U openai ddgs yfinance
export OPENAI_API_KEY="your-openai-api-key"
python callable_tools.py

On Windows PowerShell, use $Env:OPENAI_API_KEY="your-openai-api-key".

Callable Caching Settings

Factory results are cached by default. The cache key is resolved in this order: custom key function > user_id > session_id. If none are available, caching is skipped and the factory runs every time.

Setting	Default	Description
`cache_callables`	`True`	Enable or disable caching for all callable factories
`callable_tools_cache_key`	`None`	Custom cache key function for tools factory
`callable_knowledge_cache_key`	`None`	Custom cache key function for knowledge factory
`callable_members_cache_key`	`None`	Custom cache key function for members factory (Team only)

Set cache_callables=False when session_state changes between runs and the factory should re-evaluate each time.

Clear cached results by passing the Agent or Team instance to clear_callable_cache(). For example, this helper clears its cached tools and closes resources that expose a synchronous .close() method:

from agno.agent import Agent
from agno.team import Team
from agno.utils.callables import clear_callable_cache


def reset_tool_factory(entity: Agent | Team) -> None:
    clear_callable_cache(entity, kind="tools", close=True)

Omit kind to clear every factory cache on that instance. close=False (the default) removes cached results without closing them. Use aclear_callable_cache() in async code.

Next Steps

After getting familiar with the basics, add functionality as needed:

Task	Guide
Run agents	Running agents
Debug agents	Debugging agents
Manage sessions	Agent sessions
Handle input/output	Input and output
Add tools	Tools
Manage context	Context engineering
Add knowledge	Knowledge
Handle images, audio, video, files	Multimodal
Add guardrails	Guardrails
Cache responses during development	Response caching

Before you run

Run your Agent

Callable Factories

Callable Caching Settings

Next Steps

On this page