Repository: agno-agi/agno

Stars: 39500

.cursorrules Copy Chapter

You are an expert in Python, Agno framework, and AI agent development.

Core Rules
- NEVER create agents in loops - reuse them for performance
- Always use output_schema for structured responses
- PostgreSQL in production, SQLite for dev only
- Start with single agent, scale up only when needed

Documentation:
- Don't use f-strings for print lines where there are no variables to format.
- Don't use emojis in examples and print lines

Basic Agent (start here):

from agno.agent import Agent
from agno.models.openai import OpenAIChat
agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    instructions="You are a helpful assistant",
    markdown=True,
)
agent.print_response("Your query", stream=True)

Agent with Tools:

from agno.tools.websearch import WebSearchTools
agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[WebSearchTools()],
    instructions="Search the web for information",
)

CRITICAL: Agent Reuse Performance

WRONG - Recreates agent every time (significant overhead)

for query in queries:
    agent = Agent(...)  # DON'T DO THIS
    
CORRECT - Create once, reuse

agent = Agent(...)
for query in queries:
    agent.run(query)

When to Use Each Pattern

Single Agent (90% of use cases):
- One clear task or domain
- Can be solved with tools + instructions
- Example: Search, analyze, generate content

Team (autonomous coordination):
- Multiple specialized agents with different expertise
- Agents decide who does what via LLM
- Complex tasks requiring multiple perspectives
- Example: Research + Analysis + Writing

Workflow (programmatic control):
- Sequential steps with clear flow
- Need conditional logic or branching
- Full control over execution order
- Example: Extract → Transform → Load pipelines

Team Pattern:

from agno.team.team import Team
web_agent = Agent(
    name="Researcher",
    model=OpenAIChat(id="gpt-4o"),
    tools=[WebSearchTools()],
)
writer_agent = Agent(
    name="Writer",
    model=OpenAIChat(id="gpt-4o"),
)
team = Team(
    members=[web_agent, writer_agent],
    model=OpenAIChat(id="gpt-4o"),
    instructions="Research and write articles",
)

Workflow Pattern:

from agno.workflow.workflow import Workflow
from agno.db.sqlite import SqliteDb
Define agents first (researcher, writer)

async def blog_workflow(session_state, topic: str):
    # Step 1: Research
    research = await researcher.arun(topic)
    
    # Step 2: Write
    article = await writer.arun(research.content)
    
    return article
workflow = Workflow(
    name="Blog Generator",
    steps=blog_workflow,
    db=SqliteDb(db_file="tmp/workflow.db"),
)

Knowledge/RAG:

from agno.knowledge.knowledge import Knowledge
from agno.vectordb.lancedb import LanceDb, SearchType
from agno.knowledge.embedder.openai import OpenAIEmbedder
knowledge = Knowledge(
    vector_db=LanceDb(
        uri="tmp/lancedb",
        table_name="knowledge_base",
        search_type=SearchType.hybrid,
        embedder=OpenAIEmbedder(id="text-embedding-3-small"),
    ),
)
agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    knowledge=knowledge,
    search_knowledge=True,  # Critical: enables agentic RAG
    instructions="Use knowledge base, cite sources"
)

Chat History:

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    db=SqliteDb(db_file="tmp/agents.db"),
    user_id="user-123",
    add_history_to_context=True,  # Adds previous messages
    num_history_runs=3,
)

Structured Output:

from pydantic import BaseModel
class Result(BaseModel):
    summary: str
    findings: list[str]
agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    output_schema=Result,
)
result: Result = agent.run(query).content

AgentOS Production:

from agno.os import AgentOS
from agno.db.postgres import PostgresDb
agent_os = AgentOS(
    agents=[agent],
    db=PostgresDb(db_url=os.getenv("DATABASE_URL")),
)
app = agent_os.get_app()

Common Mistakes
- Creating agents in loops (massive performance hit)
- Using Team when single agent would work
- Forgetting search_knowledge=True with knowledge
- Using SQLite in production
- Not adding history when context matters
- Missing output_schema validation

Production
- Use PostgresDb not SqliteDb
- Set show_tool_calls=False, debug_mode=False
- Wrap agent.run() in try-except

Docs: https://docs.agno.com

CLAUDE.md Copy Chapter

CLAUDE.md — Agno

Instructions for Claude Code when working on this codebase.

---

Repository Structure Copy Chapter

.
├── libs/agno/agno/          # Core framework code
├── cookbook/                # Examples, patterns and test cases (organized by topic)
├── scripts/                 # Development and build scripts
├── specs/                   # Design documents (symlinked, private)
├── docs/                    # Documentation (symlinked, private)
└── .cursorrules             # Coding patterns and conventions

---

Conductor Notes Copy Chapter

When working in Conductor, you can use the .context/ directory for scratch notes or agent-to-agent handoff artifacts. This directory is gitignored.

---

Setting Up Symlinks Copy Chapter

The specs/ and docs/ directories are symlinked from external locations. For a fresh clone or new workspace, create these symlinks:

ln -s ~/code/specs specs
ln -s ~/code/docs docs

These contain private design documents and documentation that are not checked into the repository.

---

Virtual Environments Copy Chapter

This project uses two virtual environments:

| Environment | Purpose | Setup |
|-------------|---------|-------|
| .venv/ | Development: tests, formatting, validation | ./scripts/dev_setup.sh |
| .venvs/demo/ | Cookbooks: has all demo dependencies | ./scripts/demo_setup.sh |

Use .venv for development tasks (pytest, ./scripts/format.sh, ./scripts/validate.sh).

Use .venvs/demo for running cookbook examples.

---

Testing Cookbooks Copy Chapter

Apart from implementing features, your most important task will be to test and maintain the cookbooks in cookbook/ directory.

See cookbook/08_learning/ for the golden standard.

Quick Reference Copy Section

Test Environment:

Virtual environment with all dependencies

.venvs/demo/bin/python
Setup (if needed)

./scripts/demo_setup.sh
Database (if needed)

./cookbook/scripts/run_pgvector.sh

Run a cookbook:

.venvs/demo/bin/python cookbook/<folder>/<file>.py

Expected Cookbook Structure Copy Section

Each cookbook folder should have the following files:
- README.md — The README for the cookbook.
- TEST_LOG.md — Test results log.

Testing Workflow Copy Section

1. Before Testing
- Ensure the virtual environment exists (run ./scripts/demo_setup.sh if needed)
- Start any required services (e.g., ./cookbook/scripts/run_pgvector.sh)

2. Running Tests

Run individual cookbook

.venvs/demo/bin/python cookbook/<folder>/<file>.py
Tail output for long tests

.venvs/demo/bin/python cookbook/<folder>/<file>.py 2>&1 | tail -100

3. Updating TEST_LOG.md

After each test, update the cookbook's TEST_LOG.md with:
- Test name and path
- Status: PASS or FAIL
- Brief description of what was tested
- Any notable observations or issues

Format:

filename.py  Copy Section
Status: PASS/FAIL
Description: What the test does and what was observed.
Result: Summary of success/failure.
---

---

Code Locations Copy Chapter

| What | Where |
|------|-------|
| Core agent code | libs/agno/agno/agent/ |
| Teams | libs/agno/agno/team/ |
| Workflows | libs/agno/agno/workflow/ |
| Tools | libs/agno/agno/tools/ |
| Models | libs/agno/agno/models/ |
| Knowledge/RAG | libs/agno/agno/knowledge/ |
| Memory | libs/agno/agno/memory/ |
| Learning | libs/agno/agno/learn/ |
| Database adapters | libs/agno/agno/db/ |
| Vector databases | libs/agno/agno/vectordb/ |
| Tests | libs/agno/tests/ |

---

Coding Patterns Copy Chapter

See .cursorrules for detailed patterns. Key rules:

- Never create agents in loops — reuse them for performance
- Use output_schema for structured responses
- PostgreSQL in production, SQLite for dev only
- Start with single agent, scale up only when needed
- Both sync and async — all public methods need both variants

---

Running Code Copy Chapter

Running cookbooks:

.venvs/demo/bin/python cookbook/<folder>/<file>.py

Running tests:

source .venv/bin/activate
pytest libs/agno/tests/
Run a specific test file

pytest libs/agno/tests/unit/test_agent.py

---

When Implementing Features Copy Chapter

1. Check for design doc in specs/ — if it exists, follow it
2. Look at existing patterns — find similar code and follow conventions
3. Create a cookbook — every pattern should have an example
4. Update implementation.md — mark what's done

---

Before Submitting Code Copy Chapter

Always run these scripts before pushing code or creating a PR:

Activate the virtual environment first

source .venv/bin/activate
Format all code (ruff format)

./scripts/format.sh
Validate all code (ruff check, mypy)

./scripts/validate.sh

Both scripts must pass with no errors before code review.

PR Title Format:

PR titles must follow one of these formats:
- type: description — e.g., feat: add workflow serialization
- [type] description — e.g., [feat] add workflow serialization
- type-kebab-case — e.g., feat-workflow-serialization

Valid types: feat, fix, cookbook, test, refactor, chore, style, revert, release

PR Description:

Always follow the PR template in .github/pull_request_template.md. Include:
- Summary of changes
- Type of change (bug fix, new feature, etc.)
- Completed checklist items
- Any additional context

---

GitHub Operations Copy Chapter

Updating PR descriptions:

The gh pr edit command may fail with GraphQL errors related to classic projects. Use the API directly instead:

Update PR body

gh api repos/agno-agi/agno/pulls/<PR_NUMBER> -X PATCH -f body="<PR_BODY>"
Or with a file

gh api repos/agno-agi/agno/pulls/<PR_NUMBER> -X PATCH -f body="$(cat /path/to/body.md)"

---

Don't Copy Chapter

- Don't implement features without checking for a design doc first
- Don't use f-strings for print lines where there are no variables
- Don't use emojis in examples and print lines
- Don't skip async variants of public methods
- Don't push code without running ./scripts/format.sh and ./scripts/validate.sh
- Don't submit a PR without a detailed PR description. Always follow the PR template provided in .github/pull_request_template.md.
- Don't use OpenAIChat in cookbooks or examples — use OpenAIResponses instead
- Don't use gpt-4o or gpt-4o-mini in cookbooks or examples — use gpt-5.4 instead

---

CI: Automated Code Review Copy Chapter

Every non-draft PR automatically receives a review from Opus using both code-review and pr-review-toolkit official plugins (10 specialized agents total). No manual trigger needed — the review posts as a sticky comment on the PR.

When running in GitHub Actions (CI), always end your response with a plain-text summary of findings. Never let the final action be a tool call. If there are no issues, say "No high-confidence findings."

Agno-specific checks to always verify:
- Both sync and async variants exist for all new public methods
- No agent creation inside loops (agents should be reused)
- CLAUDE.md coding patterns are followed
- No f-strings for print lines where there are no variables

README.md Copy Chapter

<div align="center" id="top">
<a href="https://agno.com">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://agno-public.s3.us-east-1.amazonaws.com/assets/logo-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://agno-public.s3.us-east-1.amazonaws.com/assets/logo-light.svg">
<img src="https://agno-public.s3.us-east-1.amazonaws.com/assets/logo-light.svg" alt="Agno">
</picture>
</a>
</div>

<p align="center">
Build, run, and manage agentic software at scale.
</p>

<div align="center">
<a href="https://docs.agno.com">Docs</a>
<span>&nbsp;•&nbsp;</span>
<a href="https://github.com/agno-agi/agno/tree/main/cookbook">Cookbook</a>
<span>&nbsp;•&nbsp;</span>
<a href="https://docs.agno.com/first-agent">Quickstart</a>
<span>&nbsp;•&nbsp;</span>
<a href="https://www.agno.com/discord">Discord</a>
</div>

What is Agno Copy Chapter

Agno is the runtime for agentic software. Build agents, teams, and workflows. Run them as scalable services. Monitor and manage them in production.

| Layer | What it does |
|-------|--------------|
| Framework | Build agents, teams, and workflows with memory, knowledge, guardrails, and 100+ integrations. |
| Runtime | Serve your system in production with a stateless, session-scoped FastAPI backend. |
| Control Plane | Test, monitor, and manage your system using the AgentOS UI. |

Quick Start Copy Chapter

Build a stateful, tool-using agent and serve it as a production API in ~20 lines.

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.anthropic import Claude
from agno.os import AgentOS
from agno.tools.mcp import MCPTools
agno_assist = Agent(
    name="Agno Assist",
    model=Claude(id="claude-sonnet-4-6"),
    db=SqliteDb(db_file="agno.db"),
    tools=[MCPTools(url="https://docs.agno.com/mcp")],
    add_history_to_context=True,
    num_history_runs=3,
    markdown=True,
)
agent_os = AgentOS(agents=[agno_assist], tracing=True)
app = agent_os.get_app()

Run it:

export ANTHROPIC_API_KEY="*"
uvx --python 3.12 \
  --with "agno[os]" \
  --with anthropic \
  --with mcp \
  fastapi dev agno_assist.py

In ~20 lines, you get:
- A stateful agent with streaming responses
- Per-user, per-session isolation
- A production API at http://localhost:8000
- Native tracing

Connect to the AgentOS UI to monitor, manage, and test your agents.

1. Open os.agno.com and sign in.
2. Click "Add new OS" in the top navigation.
3. Select "Local" to connect to a local AgentOS.
4. Enter your endpoint URL (default: http://localhost:8000).
5. Name it "Local AgentOS".
6. Click "Connect".

https://github.com/user-attachments/assets/75258047-2471-4920-8874-30d68c492683

Open Chat, select your agent, and ask:

What is Agno?

The agent retrieves context from the Agno MCP server and responds with grounded answers.

https://github.com/user-attachments/assets/24c28d28-1d17-492c-815d-810e992ea8d2

You can use this exact same architecture for running multi-agent systems in production.

Why Agno? Copy Chapter

Agentic software introduces three fundamental shifts.

A new interaction model Copy Section

Traditional software receives a request and returns a response. Agents stream reasoning, tool calls, and results in real time. They can pause mid-execution, wait for approval, and resume later.

Agno treats streaming and long-running execution as first-class behavior.

A new governance model Copy Section

Traditional systems execute predefined decision logic written in advance. Agents choose actions dynamically. Some actions are low risk. Some require user approval. Some require administrative authority.

Agno lets you define who decides what as part of the agent definition, with:

- Approval workflows
- Human-in-the-loop
- Audit logs
- Enforcement at runtime

A new trust model Copy Section

Traditional systems are designed to be predictable. Every execution path is defined in advance. Agents introduce probabilistic reasoning into the execution path.

Agno builds trust into the engine itself:

- Guardrails run as part of execution
- Evaluations integrate into the agent loop
- Traces and audit logs are first-class

Built for Production Copy Chapter

Agno runs in your infrastructure, not ours.

- Stateless, horizontally scalable runtime.
- 50+ APIs and background execution.
- Per-user and per-session isolation.
- Runtime approval enforcement.
- Native tracing and full auditability.
- Sessions, memory, knowledge, and traces stored in your database.

You own the system. You own the data. You define the rules.

What You Can Build Copy Chapter

Agno powers real agentic systems built from the same primitives above.

- Pal → A personal agent that learns your preferences.
- Dash → A self-learning data agent grounded in six layers of context.
- Scout → A self-learning context agent that manages enterprise context knowledge.
- Gcode → A post-IDE coding agent that improves over time.
- Investment Team → A multi-agent investment committee that debates and allocates capital.

Single agents. Coordinated teams. Structured workflows. All built on one architecture.

Get Started Copy Chapter

1. Read the docs
2. Build your first agent
3. Explore the cookbook

IDE Integration Copy Chapter

Add Agno docs as a source in your coding tools:

Cursor: Settings → Indexing & Docs → Add https://docs.agno.com/llms-full.txt

Also works with VSCode, Windsurf, and similar tools.

Contributing Copy Chapter

See the contributing guide.

Telemetry Copy Chapter

Agno logs which model providers are used to prioritize updates. Disable with AGNO_TELEMETRY=false.

<p align="right"><a href="#top">↑ Back to top</a></p>