Building Agents

Start simple: a model, tools, and instructions.

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)

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:
        print(chunk.content)

Callable Factories

Pass a function for tools or knowledge when they should be resolved at run start.

callable_factories.py

from agno.agent import Agent
from agno.knowledge.text import TextKnowledgeBase
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()]


def get_knowledge(run_context: RunContext):
    tenant = (run_context.session_state or {}).get("tenant", "default")
    return TextKnowledgeBase(path=f"./data/{tenant}.txt")


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

Factories can declare run_context, session_state, or agent. Agno injects matching arguments by name.

Callable caching

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

Setting	Default	Description
cache_callables	True	Enable or disable caching for callable tools and knowledge factories
callable_tools_cache_key	None	Custom cache key function for the tools factory
callable_knowledge_cache_key	None	Custom cache key function for the knowledge factory

Set cache_callables=False when the factory depends on changing session_state and should re-evaluate on every run.

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