Guia Completo de Agno

🌱Fundamentos do Agno

Agno (antigo Phidata) é um framework Python full-stack para construir sistemas agênticos. A equação mental é simples: Agent = Model + Tools + Instructions. Ele se posiciona como o runtime para software agêntico, oferecendo camadas de framework, runtime (FastAPI stateless) e uma control plane (AgentOS).

Por que Agno e não LangChain/LlamaIndex?

• Performance: instanciar um Agent leva ~3μs e consome ~6.5KiB — ordens de grandeza menor que LangChain.
• Model-agnostic: suporta 20+ provedores (OpenAI, Anthropic, Groq, Together, Gemini, Mistral, Ollama...).
• Nativamente multimodal: texto, imagem, áudio e vídeo como cidadãos de primeira classe.
• Production-ready: sessions, memória, storage, observabilidade e deploy em FastAPI out of the box.

# Instalacao
pip install -U agno

# Providers populares (instale o que for usar)
pip install openai anthropic groq google-genai
pip install duckduckgo-search yfinance lancedb tantivy

Seu primeiro agente em 8 linhas

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

agent = Agent(
    model=OpenAIChat(id="gpt-5-mini"),
    description="Voce e um assistente tecnico objetivo.",
    instructions=["Responda em portugues do Brasil.", "Seja conciso."],
    markdown=True,
)

agent.print_response("Explique o que e um LLM em 3 bullets.", stream=True)

Anatomia de um Agent

🤖Agents & Models

A classe Agent é o coração do Agno. Ela encapsula um loop de controle stateful sobre um modelo stateless: recebe uma mensagem, decide se chama tools, processa resultados e retorna a resposta final.

Parâmetros mais usados

from agno.agent import Agent
from agno.models.anthropic import Claude

agent = Agent(
    # Modelo
    model=Claude(id="claude-sonnet-4-5"),

    # Identidade e comportamento
    name="Analista Financeiro",
    description="Especialista em analise fundamentalista de acoes brasileiras.",
    instructions=[
        "Sempre cite a fonte dos dados.",
        "Use tabelas Markdown para comparar ativos.",
        "Nunca de recomendacao de compra/venda - apenas analise.",
    ],
    goal="Ajudar investidores a entender fundamentos antes de decidir.",

    # Output
    markdown=True,
    show_tool_calls=True,     # mostra as chamadas de tools no terminal
    debug_mode=False,

    # Controle do loop
    tool_call_limit=10,       # maximo de tool calls por run
    reasoning=False,          # habilita chain-of-thought explicito
)

# Execucao sincrona
response = agent.run("Compare ITSA4 e B3SA3 em 3 metricas.")
print(response.content)

# Execucao em streaming (tokens conforme chegam)
agent.print_response("Compare ITSA4 e B3SA3 em 3 metricas.", stream=True)

Trocando de modelo — model-agnostic de verdade

from agno.agent import Agent

# OpenAI
from agno.models.openai import OpenAIChat
agent = Agent(model=OpenAIChat(id="gpt-5-mini"))

# Anthropic
from agno.models.anthropic import Claude
agent = Agent(model=Claude(id="claude-sonnet-4-5"))

# Groq (inferencia ultra-rapida)
from agno.models.groq import Groq
agent = Agent(model=Groq(id="llama-3.3-70b-versatile"))

# Google Gemini
from agno.models.google import Gemini
agent = Agent(model=Gemini(id="gemini-2.5-flash"))

# Together AI (open-source models)
from agno.models.together import Together
agent = Agent(model=Together(id="meta-llama/Llama-3.3-70B-Instruct-Turbo"))

# Ollama local (sem API key)
from agno.models.ollama import Ollama
agent = Agent(model=Ollama(id="llama3.2"))

Streaming e eventos estruturados

from typing import Iterator
from agno.agent import Agent, RunOutputEvent, RunEvent
from agno.models.openai import OpenAIChat

agent = Agent(model=OpenAIChat(id="gpt-5-mini"), markdown=True)

stream: Iterator[RunOutputEvent] = agent.run(
    "Liste 3 tendencias em IA para 2026.",
    stream=True,
    stream_intermediate_steps=True,  # eventos de tool call tambem
)

for chunk in stream:
    if chunk.event == RunEvent.run_content:
        print(chunk.content, end="", flush=True)
    elif chunk.event == RunEvent.tool_call_started:
        print(f"\n[tool] {chunk.tool.tool_name}({chunk.tool.tool_args})")

Escolhendo o modelo certo

🛠Tools

Tools são funções Python que o LLM pode invocar. Agno oferece 100+ tools built-in (busca web, APIs financeiras, código, bancos, filesystem...) e permite criar tools customizadas em segundos.

Tools built-in mais usados

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.duckduckgo import DuckDuckGoTools
from agno.tools.yfinance import YFinanceTools
from agno.tools.calculator import CalculatorTools

agent = Agent(
    model=OpenAIChat(id="gpt-5-mini"),
    tools=[
        DuckDuckGoTools(),
        YFinanceTools(
            stock_price=True,
            analyst_recommendations=True,
            company_info=True,
            company_news=True,
        ),
        CalculatorTools(enable_all=True),
    ],
    instructions=[
        "Use DuckDuckGo para noticias recentes.",
        "Use YFinance para dados financeiros.",
        "Mostre os resultados em tabelas.",
    ],
    show_tool_calls=True,
    markdown=True,
)

agent.print_response(
    "Qual o preco atual da NVDA e as ultimas noticias? Calcule o P/L se EPS = 2.94.",
    stream=True,
)

Tool customizado — função Python simples

import httpx
from agno.agent import Agent
from agno.models.openai import OpenAIChat

def get_weather(city: str) -> str:
    """Retorna clima atual de uma cidade via API publica.

    Args:
        city: Nome da cidade (ex: "Sao Paulo", "Rio de Janeiro").
    """
    url = f"https://wttr.in/{city}?format=j1"
    data = httpx.get(url, timeout=10).json()
    c = data["current_condition"][0]
    return f"{city}: {c['temp_C']}C, {c['weatherDesc'][0]['value']}"

agent = Agent(
    model=OpenAIChat(id="gpt-5-mini"),
    tools=[get_weather],          # passe a funcao direto
    instructions=["Use o tool get_weather quando perguntarem sobre clima."],
    show_tool_calls=True,
    markdown=True,
)

agent.print_response("Como esta o tempo em Curitiba agora?")

Tools com decorator @tool (controle fino)

from agno.tools import tool
from agno.agent import Agent
from agno.models.openai import OpenAIChat

@tool(
    name="buscar_cep",
    description="Consulta endereco brasileiro a partir de um CEP.",
    show_result=True,             # mostra o retorno no output do agente
    stop_after_tool_call=False,   # nao encerra o run apos retornar
    cache_results=True,           # cacheia chamadas identicas
    cache_ttl=3600,
)
def buscar_cep(cep: str) -> dict:
    """Busca endereco por CEP via ViaCEP."""
    import httpx
    cep_clean = "".join(filter(str.isdigit, cep))
    r = httpx.get(f"https://viacep.com.br/ws/{cep_clean}/json/", timeout=10)
    return r.json()

agent = Agent(
    model=OpenAIChat(id="gpt-5-mini"),
    tools=[buscar_cep],
    tool_call_limit=5,
    show_tool_calls=True,
    markdown=True,
)

agent.print_response("Qual o endereco do CEP 01310-100?")

Catálogo de tools built-in

📚Knowledge & Embeddings (Agentic RAG)

Agno chama sua abordagem de RAG de Agentic RAG: o agente decide quando buscar no knowledge base, reformula a query se necessário e cita fontes. Você conecta loaders, um vector DB e embeddings.

PDF Knowledge + LanceDB

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.embedder.openai import OpenAIEmbedder
from agno.knowledge.pdf import PDFKnowledgeBase, PDFReader
from agno.vectordb.lancedb import LanceDb, SearchType

# Vector DB local (LanceDB e embedded, sem servidor)
vector_db = LanceDb(
    table_name="manuais",
    uri="tmp/lancedb",
    search_type=SearchType.hybrid,     # vetorial + full-text BM25
    embedder=OpenAIEmbedder(id="text-embedding-3-small", dimensions=1536),
)

# Knowledge base a partir de um diretorio de PDFs
knowledge = PDFKnowledgeBase(
    path="data/pdfs",
    vector_db=vector_db,
    reader=PDFReader(chunk=True),
    num_documents=5,       # top-k documentos retornados por busca
)

# Indexa os PDFs (rode uma vez; use recreate=True para reindexar)
knowledge.load(recreate=False)

agent = Agent(
    model=OpenAIChat(id="gpt-5-mini"),
    knowledge=knowledge,
    search_knowledge=True,            # habilita tool de busca no KB
    add_context=True,                 # injeta contexto relevante no prompt
    instructions=[
        "Responda APENAS com base no knowledge base.",
        "Sempre cite o arquivo e pagina da fonte.",
        "Se nao souber, diga 'nao encontrei essa informacao'.",
    ],
    markdown=True,
)

agent.print_response("Qual o procedimento de backup descrito no manual?")

Website Knowledge — crawla um site inteiro

from agno.knowledge.website import WebsiteKnowledgeBase
from agno.vectordb.lancedb import LanceDb

knowledge = WebsiteKnowledgeBase(
    urls=["https://docs.agno.com"],
    max_links=50,                     # limite de paginas crawladas
    max_depth=3,                      # profundidade de links
    vector_db=LanceDb(
        table_name="agno_docs",
        uri="tmp/lancedb",
        embedder=OpenAIEmbedder(id="text-embedding-3-small"),
    ),
)
knowledge.load(recreate=True)

Outros loaders úteis

# CSV
from agno.knowledge.csv import CSVKnowledgeBase
kb = CSVKnowledgeBase(path="data/produtos.csv", vector_db=vector_db)

# JSON
from agno.knowledge.json import JSONKnowledgeBase
kb = JSONKnowledgeBase(path="data/faq.json", vector_db=vector_db)

# Markdown / MDX
from agno.knowledge.text import TextKnowledgeBase
kb = TextKnowledgeBase(path="content/", formats=[".md", ".mdx"], vector_db=vector_db)

# S3
from agno.knowledge.s3.pdf import S3PDFKnowledgeBase
kb = S3PDFKnowledgeBase(bucket_name="meus-docs", vector_db=vector_db)

# Wikipedia
from agno.knowledge.wikipedia import WikipediaKnowledgeBase
kb = WikipediaKnowledgeBase(topics=["agentic AI", "RAG"], vector_db=vector_db)

Vector DBs suportados

💾Memory & Storage

Agno separa dois conceitos complementares: Storage persiste o histórico de mensagens da sessão, e Memory armazena fatos de longo prazo sobre o usuário (preferências, perfil, histórico).

Storage — histórico de conversa

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.storage.sqlite import SqliteStorage

storage = SqliteStorage(
    table_name="agent_sessions",
    db_file="tmp/agent.db",
)

agent = Agent(
    model=OpenAIChat(id="gpt-5-mini"),
    storage=storage,
    session_id="user-42-chat",              # identifica a sessao
    user_id="user-42",
    add_history_to_messages=True,           # injeta historico no prompt
    num_history_responses=5,                # ultimas 5 interacoes
    read_chat_history=True,                 # da ao agente uma tool para ler o historico
    markdown=True,
)

agent.print_response("Meu nome e Kaique.")
agent.print_response("Qual o meu nome?")   # deve lembrar, mesmo entre processes

Memory (v2) — fatos persistentes sobre o usuário

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.memory.v2.db.sqlite import SqliteMemoryDb
from agno.memory.v2.memory import Memory

memory_db = SqliteMemoryDb(table_name="user_memories", db_file="tmp/memory.db")

memory = Memory(
    model=OpenAIChat(id="gpt-5-mini"),      # modelo que extrai os fatos
    db=memory_db,
)

agent = Agent(
    model=OpenAIChat(id="gpt-5-mini"),
    user_id="user-42",
    memory=memory,
    enable_agentic_memory=True,             # agente decide quando gravar
    enable_user_memories=True,              # gravacao automatica ao fim da run
    markdown=True,
)

agent.print_response("Eu sou desenvolvedor Full Stack, especializado em Go e Next.js.")
agent.print_response("Moro em Curitiba e invisto em FIIs desde 2020.")

# Mais tarde, em outra sessao
agent.print_response("Que tecnologias combinam com o meu perfil?")
# O agente recupera os memories do usuario e personaliza a resposta.

Drivers de storage/memory

# SQLite (dev / single-node)
from agno.storage.sqlite import SqliteStorage
from agno.memory.v2.db.sqlite import SqliteMemoryDb

# PostgreSQL (producao)
from agno.storage.postgres import PostgresStorage
from agno.memory.v2.db.postgres import PostgresMemoryDb

storage = PostgresStorage(
    table_name="sessions",
    db_url="postgresql+psycopg://user:pass@localhost:5432/agno",
)

# MongoDB
from agno.storage.mongodb import MongoDbStorage

# DynamoDB (serverless)
from agno.storage.dynamodb import DynamoDbStorage

# Redis (cache efemero de sessoes)
from agno.storage.redis import RedisStorage

# YAML/JSON (bom para prototipagem local)
from agno.storage.yaml import YamlStorage
from agno.storage.json import JsonStorage

🏗Teams, Workflows & AgentOS

Agno escala para sistemas multi-agente (Teams), pipelines determinísticos (Workflows) e expõe tudo como API FastAPI via AgentOS. Isso fecha o ciclo do protótipo até produção sem trocar de framework.

Team — colaboração entre especialistas

from agno.agent import Agent
from agno.team import Team
from agno.models.openai import OpenAIChat
from agno.tools.duckduckgo import DuckDuckGoTools
from agno.tools.yfinance import YFinanceTools

pesquisador = Agent(
    name="Pesquisador",
    role="Busca noticias recentes e contexto de mercado.",
    model=OpenAIChat(id="gpt-5-mini"),
    tools=[DuckDuckGoTools()],
    instructions=["Sempre retorne fontes com URL."],
)

analista = Agent(
    name="Analista Financeiro",
    role="Calcula metricas fundamentalistas de acoes.",
    model=OpenAIChat(id="gpt-5-mini"),
    tools=[YFinanceTools(stock_price=True, analyst_recommendations=True)],
    instructions=["Use tabelas Markdown."],
)

time = Team(
    name="Equipe de Analise",
    mode="coordinate",                       # coordinator delega as sub-agentes
    model=OpenAIChat(id="gpt-5"),            # modelo "coordenador" mais forte
    members=[pesquisador, analista],
    instructions=[
        "Pesquisador busca noticias, Analista calcula metricas.",
        "Combine os outputs em um relatorio final.",
    ],
    show_members_responses=True,
    markdown=True,
)

time.print_response("Analise completa da NVDA: noticias + fundamentos.", stream=True)

Workflow — pipeline determinístico em passos

from agno.workflow.v2 import Workflow, Step
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.duckduckgo import DuckDuckGoTools

pesquisa = Agent(model=OpenAIChat(id="gpt-5-mini"), tools=[DuckDuckGoTools()])
redator  = Agent(
    model=OpenAIChat(id="gpt-5-mini"),
    instructions=["Escreva um artigo em Markdown, 600 palavras, tom tecnico."],
)

workflow = Workflow(
    name="Pipeline de Conteudo",
    steps=[
        Step(name="pesquisa", agent=pesquisa, description="Coleta fontes"),
        Step(name="redacao",  agent=redator,  description="Gera o artigo"),
    ],
)

result = workflow.run(message="Tendencias de AI Engineering em 2026")
print(result.content)

AgentOS — FastAPI + UI em 3 linhas

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.os import AgentOS

agent = Agent(model=OpenAIChat(id="gpt-5-mini"), markdown=True)

os_app = AgentOS(agents=[agent])          # gera API FastAPI + playground UI
app = os_app.get_app()                    # ASGI app pronto para uvicorn

if __name__ == "__main__":
    os_app.serve(app="main:app", reload=True)
    # Abre http://localhost:7777 com playground + docs Swagger
    # Rotas automaticas: POST /agents/{id}/runs, GET /sessions, etc.

Observabilidade com agno.com

# Habilita monitoramento em todas as runs
agent = Agent(
    model=OpenAIChat(id="gpt-5-mini"),
    monitoring=True,                       # envia traces para agno.com
    telemetry=True,                        # metricas anonimas
)

# Ou por ambiente:
# export AGNO_MONITOR=true
# export AGNO_API_KEY=...

Teams: modos de operação

Deploy típico

1. Defina agentes/times/workflows em main.py.
2. Exponha via AgentOS(agents=[...]).get_app().
3. Empacote em Docker com uvicorn main:app --host 0.0.0.0 --port 7777.
4. Deploy em ECS, Cloud Run, Fly.io ou Kubernetes — é FastAPI comum.
5. Ative monitoring=True para ver traces no AgentOS UI.