{"owner":"agno-agi","repo":"agno","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md","AGENTS.md",".cursorrules"],"skills":{"CLAUDE.md":"# CLAUDE.md — Agno\n\nInstructions for Claude Code when working on this codebase.\n\n---\n\n## Repository Structure\n\n```\n.\n├── libs/agno/agno/          # Core framework code\n├── cookbook/                # Examples, patterns and test cases (organized by topic)\n├── scripts/                 # Development and build scripts\n├── specs/                   # Design documents (symlinked, private)\n├── docs/                    # Documentation (symlinked, private)\n└── .cursorrules             # Coding patterns and conventions\n```\n\n---\n\n## Conductor Notes\n\nWhen working in Conductor, you can use the `.context/` directory for scratch notes or agent-to-agent handoff artifacts. This directory is gitignored.\n\n---\n\n## Setting Up Symlinks\n\nThe `specs/` and `docs/` directories are symlinked from external locations. For a fresh clone or new workspace, create these symlinks:\n\n```bash\nln -s ~/code/specs specs\nln -s ~/code/docs docs\n```\n\nThese contain private design documents and documentation that are not checked into the repository.\n\n---\n\n## Virtual Environments\n\nThis project uses two virtual environments:\n\n| Environment | Purpose | Setup |\n|-------------|---------|-------|\n| `.venv/` | Development: tests, formatting, validation | `./scripts/dev_setup.sh` |\n| `.venvs/demo/` | Cookbooks: has all demo dependencies | `./scripts/demo_setup.sh` |\n\n**Use `.venv`** for development tasks (`pytest`, `./scripts/format.sh`, `./scripts/validate.sh`).\n\n**Use `.venvs/demo`** for running cookbook examples.\n\n---\n\n## Testing Cookbooks\n\nApart from implementing features, your most important task will be to test and maintain the cookbooks in `cookbook/` directory.\n\n> See `cookbook/08_learning/` for the golden standard.\n\n### Quick Reference\n\n**Test Environment:**\n\n```bash\n# Virtual environment with all dependencies\n.venvs/demo/bin/python\n\n# Setup (if needed)\n./scripts/demo_setup.sh\n\n# Database (if needed)\n./cookbook/scripts/run_pgvector.sh\n```\n\n**Run a cookbook:**\n```bash\n.venvs/demo/bin/python cookbook/<folder>/<file>.py\n```\n\n### Expected Cookbook Structure\n\nEach cookbook folder should have the following files:\n- `README.md` — The README for the cookbook.\n- `TEST_LOG.md` — Test results log.\n\n### Testing Workflow\n\n**1. Before Testing**\n- Ensure the virtual environment exists (run `./scripts/demo_setup.sh` if needed)\n- Start any required services (e.g., `./cookbook/scripts/run_pgvector.sh`)\n\n**2. Running Tests**\n```bash\n# Run individual cookbook\n.venvs/demo/bin/python cookbook/<folder>/<file>.py\n\n# Tail output for long tests\n.venvs/demo/bin/python cookbook/<folder>/<file>.py 2>&1 | tail -100\n```\n\n**3. Updating TEST_LOG.md**\n\nAfter each test, update the cookbook's `TEST_LOG.md` with:\n- Test name and path\n- Status: PASS or FAIL\n- Brief description of what was tested\n- Any notable observations or issues\n\nFormat:\n```markdown\n### filename.py\n\n**Status:** PASS/FAIL\n\n**Description:** What the test does and what was observed.\n\n**Result:** Summary of success/failure.\n\n---\n```\n\n---\n\n## Code Locations\n\n| What | Where |\n|------|-------|\n| Core agent code | `libs/agno/agno/agent/` |\n| Teams | `libs/agno/agno/team/` |\n| Workflows | `libs/agno/agno/workflow/` |\n| Tools | `libs/agno/agno/tools/` |\n| Models | `libs/agno/agno/models/` |\n| Knowledge/RAG | `libs/agno/agno/knowledge/` |\n| Memory | `libs/agno/agno/memory/` |\n| Learning | `libs/agno/agno/learn/` |\n| Database adapters | `libs/agno/agno/db/` |\n| Vector databases | `libs/agno/agno/vectordb/` |\n| Tests | `libs/agno/tests/` |\n\n---\n\n## Coding Patterns\n\nSee `.cursorrules` for detailed patterns. Key rules:\n\n- **Never create agents in loops** — reuse them for performance\n- **Use output_schema** for structured responses\n- **PostgreSQL in production**, SQLite for dev only\n- **Start with single agent**, scale up only when needed\n- **Both sync and async** — all public methods need both variants\n\n---\n\n## Running Code\n\n**Running cookbooks:**\n```bash\n.venvs/demo/bin/python cookbook/<folder>/<file>.py\n```\n\n**Running tests:**\n```bash\nsource .venv/bin/activate\npytest libs/agno/tests/\n\n# Run a specific test file\npytest libs/agno/tests/unit/test_agent.py\n```\n\n---\n\n## When Implementing Features\n\n1. **Check for design doc** in `specs/` — if it exists, follow it\n2. **Look at existing patterns** — find similar code and follow conventions\n3. **Create a cookbook** — every pattern should have an example\n4. **Update implementation.md** — mark what's done\n\n---\n\n## Before Submitting Code\n\n**Always run these scripts before pushing code or creating a PR:**\n\n```bash\n# Activate the virtual environment first\nsource .venv/bin/activate\n\n# Format all code (ruff format)\n./scripts/format.sh\n\n# Validate all code (ruff check, mypy)\n./scripts/validate.sh\n```\n\nBoth scripts must pass with no errors before code review.\n\n**PR Title Format:**\n\nPR titles must follow one of these formats:\n- `type: description` — e.g., `feat: add workflow serialization`\n- `[type] description` — e.g., `[feat] add workflow serialization`\n- `type-kebab-case` — e.g., `feat-workflow-serialization`\n\nValid types: `feat`, `fix`, `cookbook`, `test`, `refactor`, `chore`, `style`, `revert`, `release`\n\n**PR Description:**\n\nAlways follow the PR template in `.github/pull_request_template.md`. Include:\n- Summary of changes\n- Type of change (bug fix, new feature, etc.)\n- Completed checklist items\n- Any additional context\n\n---\n\n## GitHub Operations\n\n**Updating PR descriptions:**\n\nThe `gh pr edit` command may fail with GraphQL errors related to classic projects. Use the API directly instead:\n\n```bash\n# Update PR body\ngh api repos/agno-agi/agno/pulls/<PR_NUMBER> -X PATCH -f body=\"<PR_BODY>\"\n\n# Or with a file\ngh api repos/agno-agi/agno/pulls/<PR_NUMBER> -X PATCH -f body=\"$(cat /path/to/body.md)\"\n```\n\n---\n\n## Don't\n\n- Don't implement features without checking for a design doc first\n- Don't use f-strings for print lines where there are no variables\n- Don't use emojis in examples and print lines\n- Don't skip async variants of public methods\n- Don't push code without running `./scripts/format.sh` and `./scripts/validate.sh`\n- Don't submit a PR without a detailed PR description. Always follow the PR template provided in `.github/pull_request_template.md`.\n- Don't use `OpenAIChat` in cookbooks or examples — use `OpenAIResponses` instead\n- Don't use `gpt-4o` or `gpt-4o-mini` in cookbooks or examples — use `gpt-5.5` instead\n\n---\n\n## CI: Automated Code Review\n\nEvery 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.\n\nWhen 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.\"\n\nAgno-specific checks to always verify:\n- Both sync and async variants exist for all new public methods\n- No agent creation inside loops (agents should be reused)\n- CLAUDE.md coding patterns are followed\n- No f-strings for print lines where there are no variables\n","AGENTS.md":"# AGENTS.md — Agno\n\nInstructions for AI coding agents working on this codebase.\n\n---\n\n## Repository Structure\n\n```\n.\n├── libs/agno/agno/          # Core framework code\n├── cookbook/                # Examples, patterns and test cases (organized by topic)\n├── scripts/                 # Development and build scripts\n├── specs/                   # Design documents (symlinked, private)\n├── docs/                    # Documentation (symlinked, private)\n└── .cursorrules             # Coding patterns and conventions\n```\n\n---\n\n## Conductor Notes\n\nWhen working in Conductor, you can use the `.context/` directory for scratch notes or agent-to-agent handoff artifacts. This directory is gitignored.\n\n---\n\n## Setting Up Symlinks\n\nThe `specs/` and `docs/` directories are symlinked from external locations. For a fresh clone or new workspace, create these symlinks:\n\n```bash\nln -s ~/code/specs specs\nln -s ~/code/docs docs\n```\n\nThese contain private design documents and documentation that are not checked into the repository.\n\n---\n\n## Virtual Environments\n\nThis project uses two virtual environments:\n\n| Environment | Purpose | Setup |\n|-------------|---------|-------|\n| `.venv/` | Development: tests, formatting, validation | `./scripts/dev_setup.sh` |\n| `.venvs/demo/` | Cookbooks: has all demo dependencies | `./scripts/demo_setup.sh` |\n\n**Use `.venv`** for development tasks (`pytest`, `./scripts/format.sh`, `./scripts/validate.sh`).\n\n**Use `.venvs/demo`** for running cookbook examples.\n\n---\n\n## Testing Cookbooks\n\nApart from implementing features, your most important task will be to test and maintain the cookbooks in `cookbook/` directory.\n\n> See `cookbook/08_learning/` for the golden standard.\n\n### Quick Reference\n\n**Test Environment:**\n\n```bash\n# Virtual environment with all dependencies\n.venvs/demo/bin/python\n\n# Setup (if needed)\n./scripts/demo_setup.sh\n\n# Database (if needed)\n./cookbook/scripts/run_pgvector.sh\n```\n\n**Run a cookbook:**\n```bash\n.venvs/demo/bin/python cookbook/<folder>/<file>.py\n```\n\n### Expected Cookbook Structure\n\nEach cookbook folder should have the following files:\n- `README.md` — The README for the cookbook.\n- `TEST_LOG.md` — Test results log.\n\n### Testing Workflow\n\n**1. Before Testing**\n- Ensure the virtual environment exists (run `./scripts/demo_setup.sh` if needed)\n- Start any required services (e.g., `./cookbook/scripts/run_pgvector.sh`)\n\n**2. Running Tests**\n```bash\n# Run individual cookbook\n.venvs/demo/bin/python cookbook/<folder>/<file>.py\n\n# Tail output for long tests\n.venvs/demo/bin/python cookbook/<folder>/<file>.py 2>&1 | tail -100\n```\n\n**3. Updating TEST_LOG.md**\n\nAfter each test, update the cookbook's `TEST_LOG.md` with:\n- Test name and path\n- Status: PASS or FAIL\n- Brief description of what was tested\n- Any notable observations or issues\n\nFormat:\n```markdown\n### filename.py\n\n**Status:** PASS/FAIL\n\n**Description:** What the test does and what was observed.\n\n**Result:** Summary of success/failure.\n\n---\n```\n\n---\n\n## Code Locations\n\n| What | Where |\n|------|-------|\n| Core agent code | `libs/agno/agno/agent/` |\n| Teams | `libs/agno/agno/team/` |\n| Workflows | `libs/agno/agno/workflow/` |\n| Tools | `libs/agno/agno/tools/` |\n| Models | `libs/agno/agno/models/` |\n| Knowledge/RAG | `libs/agno/agno/knowledge/` |\n| Memory | `libs/agno/agno/memory/` |\n| Learning | `libs/agno/agno/learn/` |\n| Database adapters | `libs/agno/agno/db/` |\n| Vector databases | `libs/agno/agno/vectordb/` |\n| Tests | `libs/agno/tests/` |\n\n---\n\n## Coding Patterns\n\nSee `.cursorrules` for detailed patterns. Key rules:\n\n- **Never create agents in loops** — reuse them for performance\n- **Use output_schema** for structured responses\n- **PostgreSQL in production**, SQLite for dev only\n- **Start with single agent**, scale up only when needed\n- **Both sync and async** — all public methods need both variants\n\n---\n\n## Running Code\n\n**Running cookbooks:**\n```bash\n.venvs/demo/bin/python cookbook/<folder>/<file>.py\n```\n\n**Running tests:**\n```bash\nsource .venv/bin/activate\npytest libs/agno/tests/\n\n# Run a specific test file\npytest libs/agno/tests/unit/test_agent.py\n```\n\n---\n\n## When Implementing Features\n\n1. **Check for design doc** in `specs/` — if it exists, follow it\n2. **Look at existing patterns** — find similar code and follow conventions\n3. **Create a cookbook** — every pattern should have an example\n4. **Update implementation.md** — mark what's done\n\n---\n\n## Before Submitting Code\n\n**Always run these scripts before pushing code or creating a PR:**\n\n```bash\n# Activate the virtual environment first\nsource .venv/bin/activate\n\n# Format all code (ruff format)\n./scripts/format.sh\n\n# Validate all code (ruff check, mypy)\n./scripts/validate.sh\n```\n\nBoth scripts must pass with no errors before code review.\n\n**PR Title Format:**\n\nPR titles must follow one of these formats:\n- `type: description` — e.g., `feat: add workflow serialization`\n- `[type] description` — e.g., `[feat] add workflow serialization`\n- `type-kebab-case` — e.g., `feat-workflow-serialization`\n\nValid types: `feat`, `fix`, `cookbook`, `test`, `refactor`, `chore`, `style`, `revert`, `release`\n\n**PR Description:**\n\nAlways follow the PR template in `.github/pull_request_template.md`. Include:\n- Summary of changes\n- Type of change (bug fix, new feature, etc.)\n- Completed checklist items\n- Any additional context\n\n---\n\n## GitHub Operations\n\n**Updating PR descriptions:**\n\nThe `gh pr edit` command may fail with GraphQL errors related to classic projects. Use the API directly instead:\n\n```bash\n# Update PR body\ngh api repos/agno-agi/agno/pulls/<PR_NUMBER> -X PATCH -f body=\"<PR_BODY>\"\n\n# Or with a file\ngh api repos/agno-agi/agno/pulls/<PR_NUMBER> -X PATCH -f body=\"$(cat /path/to/body.md)\"\n```\n\n---\n\n## Don't\n\n- Don't implement features without checking for a design doc first\n- Don't use f-strings for print lines where there are no variables\n- Don't use emojis in examples and print lines\n- Don't skip async variants of public methods\n- Don't push code without running `./scripts/format.sh` and `./scripts/validate.sh`\n- Don't submit a PR without a detailed PR description. Always follow the PR template provided in `.github/pull_request_template.md`.\n",".cursorrules":"You are an expert in Python, Agno framework, and AI agent development.\n\nCore Rules\n- NEVER create agents in loops - reuse them for performance\n- Always use output_schema for structured responses\n- PostgreSQL in production, SQLite for dev only\n- Start with single agent, scale up only when needed\n\nDocumentation:\n- Don't use f-strings for print lines where there are no variables to format.\n- Don't use emojis in examples and print lines\n\nBasic Agent (start here):\n```python\nfrom agno.agent import Agent\nfrom agno.models.openai import OpenAIResponses\n\nagent = Agent(\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    instructions=\"You are a helpful assistant\",\n    markdown=True,\n)\nagent.print_response(\"Your query\", stream=True)\n```\n\nAgent with Tools:\n```python\nfrom agno.tools.websearch import WebSearchTools\n\nagent = Agent(\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    tools=[WebSearchTools()],\n    instructions=\"Search the web for information\",\n)\n```\n\nCRITICAL: Agent Reuse Performance\n```python\n# WRONG - Recreates agent every time (significant overhead)\nfor query in queries:\n    agent = Agent(...)  # DON'T DO THIS\n    \n# CORRECT - Create once, reuse\nagent = Agent(...)\nfor query in queries:\n    agent.run(query)\n```\n\nWhen to Use Each Pattern\n\nSingle Agent (90% of use cases):\n- One clear task or domain\n- Can be solved with tools + instructions\n- Example: Search, analyze, generate content\n\nTeam (autonomous coordination):\n- Multiple specialized agents with different expertise\n- Agents decide who does what via LLM\n- Complex tasks requiring multiple perspectives\n- Example: Research + Analysis + Writing\n\nWorkflow (programmatic control):\n- Sequential steps with clear flow\n- Need conditional logic or branching\n- Full control over execution order\n- Example: Extract → Transform → Load pipelines\n\nTeam Pattern:\n```python\nfrom agno.team.team import Team\n\nweb_agent = Agent(\n    name=\"Researcher\",\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    tools=[WebSearchTools()],\n)\n\nwriter_agent = Agent(\n    name=\"Writer\",\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n)\n\nteam = Team(\n    members=[web_agent, writer_agent],\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    instructions=\"Research and write articles\",\n)\n```\n\nWorkflow Pattern:\n```python\nfrom agno.workflow.workflow import Workflow\nfrom agno.db.sqlite import SqliteDb\n\n# Define agents first (researcher, writer)\nasync def blog_workflow(session_state, topic: str):\n    # Step 1: Research\n    research = await researcher.arun(topic)\n    \n    # Step 2: Write\n    article = await writer.arun(research.content)\n    \n    return article\n\nworkflow = Workflow(\n    name=\"Blog Generator\",\n    steps=blog_workflow,\n    db=SqliteDb(db_file=\"tmp/workflow.db\"),\n)\n```\n\nKnowledge/RAG:\n```python\nfrom agno.knowledge.knowledge import Knowledge\nfrom agno.vectordb.lancedb import LanceDb, SearchType\nfrom agno.knowledge.embedder.openai import OpenAIEmbedder\n\nknowledge = Knowledge(\n    vector_db=LanceDb(\n        uri=\"tmp/lancedb\",\n        table_name=\"knowledge_base\",\n        search_type=SearchType.hybrid,\n        embedder=OpenAIEmbedder(id=\"text-embedding-3-small\"),\n    ),\n)\n\nagent = Agent(\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    knowledge=knowledge,\n    search_knowledge=True,  # Critical: enables agentic RAG\n    instructions=\"Use knowledge base, cite sources\"\n)\n```\n\nChat History:\n```python\nagent = Agent(\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    db=SqliteDb(db_file=\"tmp/agents.db\"),\n    user_id=\"user-123\",\n    add_history_to_context=True,  # Adds previous messages\n    num_history_runs=3,\n)\n```\n\nStructured Output:\n```python\nfrom pydantic import BaseModel\n\nclass Result(BaseModel):\n    summary: str\n    findings: list[str]\n\nagent = Agent(\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    output_schema=Result,\n)\nresult: Result = agent.run(query).content\n```\n\nAgentOS Production:\n```python\nfrom agno.os import AgentOS\nfrom agno.db.postgres import PostgresDb\n\nagent_os = AgentOS(\n    agents=[agent],\n    db=PostgresDb(db_url=os.getenv(\"DATABASE_URL\")),\n)\napp = agent_os.get_app()\n```\n\nCommon Mistakes\n- Creating agents in loops (massive performance hit)\n- Using Team when single agent would work\n- Forgetting search_knowledge=True with knowledge\n- Using SQLite in production\n- Not adding history when context matters\n- Missing output_schema validation\n\nProduction\n- Use PostgresDb not SqliteDb\n- Set show_tool_calls=False, debug_mode=False\n- Wrap agent.run() in try-except\n\nDocs: https://docs.agno.com\n"},"files":{"CLAUDE.md":"# CLAUDE.md — Agno\n\nInstructions for Claude Code when working on this codebase.\n\n---\n\n## Repository Structure\n\n```\n.\n├── libs/agno/agno/          # Core framework code\n├── cookbook/                # Examples, patterns and test cases (organized by topic)\n├── scripts/                 # Development and build scripts\n├── specs/                   # Design documents (symlinked, private)\n├── docs/                    # Documentation (symlinked, private)\n└── .cursorrules             # Coding patterns and conventions\n```\n\n---\n\n## Conductor Notes\n\nWhen working in Conductor, you can use the `.context/` directory for scratch notes or agent-to-agent handoff artifacts. This directory is gitignored.\n\n---\n\n## Setting Up Symlinks\n\nThe `specs/` and `docs/` directories are symlinked from external locations. For a fresh clone or new workspace, create these symlinks:\n\n```bash\nln -s ~/code/specs specs\nln -s ~/code/docs docs\n```\n\nThese contain private design documents and documentation that are not checked into the repository.\n\n---\n\n## Virtual Environments\n\nThis project uses two virtual environments:\n\n| Environment | Purpose | Setup |\n|-------------|---------|-------|\n| `.venv/` | Development: tests, formatting, validation | `./scripts/dev_setup.sh` |\n| `.venvs/demo/` | Cookbooks: has all demo dependencies | `./scripts/demo_setup.sh` |\n\n**Use `.venv`** for development tasks (`pytest`, `./scripts/format.sh`, `./scripts/validate.sh`).\n\n**Use `.venvs/demo`** for running cookbook examples.\n\n---\n\n## Testing Cookbooks\n\nApart from implementing features, your most important task will be to test and maintain the cookbooks in `cookbook/` directory.\n\n> See `cookbook/08_learning/` for the golden standard.\n\n### Quick Reference\n\n**Test Environment:**\n\n```bash\n# Virtual environment with all dependencies\n.venvs/demo/bin/python\n\n# Setup (if needed)\n./scripts/demo_setup.sh\n\n# Database (if needed)\n./cookbook/scripts/run_pgvector.sh\n```\n\n**Run a cookbook:**\n```bash\n.venvs/demo/bin/python cookbook/<folder>/<file>.py\n```\n\n### Expected Cookbook Structure\n\nEach cookbook folder should have the following files:\n- `README.md` — The README for the cookbook.\n- `TEST_LOG.md` — Test results log.\n\n### Testing Workflow\n\n**1. Before Testing**\n- Ensure the virtual environment exists (run `./scripts/demo_setup.sh` if needed)\n- Start any required services (e.g., `./cookbook/scripts/run_pgvector.sh`)\n\n**2. Running Tests**\n```bash\n# Run individual cookbook\n.venvs/demo/bin/python cookbook/<folder>/<file>.py\n\n# Tail output for long tests\n.venvs/demo/bin/python cookbook/<folder>/<file>.py 2>&1 | tail -100\n```\n\n**3. Updating TEST_LOG.md**\n\nAfter each test, update the cookbook's `TEST_LOG.md` with:\n- Test name and path\n- Status: PASS or FAIL\n- Brief description of what was tested\n- Any notable observations or issues\n\nFormat:\n```markdown\n### filename.py\n\n**Status:** PASS/FAIL\n\n**Description:** What the test does and what was observed.\n\n**Result:** Summary of success/failure.\n\n---\n```\n\n---\n\n## Code Locations\n\n| What | Where |\n|------|-------|\n| Core agent code | `libs/agno/agno/agent/` |\n| Teams | `libs/agno/agno/team/` |\n| Workflows | `libs/agno/agno/workflow/` |\n| Tools | `libs/agno/agno/tools/` |\n| Models | `libs/agno/agno/models/` |\n| Knowledge/RAG | `libs/agno/agno/knowledge/` |\n| Memory | `libs/agno/agno/memory/` |\n| Learning | `libs/agno/agno/learn/` |\n| Database adapters | `libs/agno/agno/db/` |\n| Vector databases | `libs/agno/agno/vectordb/` |\n| Tests | `libs/agno/tests/` |\n\n---\n\n## Coding Patterns\n\nSee `.cursorrules` for detailed patterns. Key rules:\n\n- **Never create agents in loops** — reuse them for performance\n- **Use output_schema** for structured responses\n- **PostgreSQL in production**, SQLite for dev only\n- **Start with single agent**, scale up only when needed\n- **Both sync and async** — all public methods need both variants\n\n---\n\n## Running Code\n\n**Running cookbooks:**\n```bash\n.venvs/demo/bin/python cookbook/<folder>/<file>.py\n```\n\n**Running tests:**\n```bash\nsource .venv/bin/activate\npytest libs/agno/tests/\n\n# Run a specific test file\npytest libs/agno/tests/unit/test_agent.py\n```\n\n---\n\n## When Implementing Features\n\n1. **Check for design doc** in `specs/` — if it exists, follow it\n2. **Look at existing patterns** — find similar code and follow conventions\n3. **Create a cookbook** — every pattern should have an example\n4. **Update implementation.md** — mark what's done\n\n---\n\n## Before Submitting Code\n\n**Always run these scripts before pushing code or creating a PR:**\n\n```bash\n# Activate the virtual environment first\nsource .venv/bin/activate\n\n# Format all code (ruff format)\n./scripts/format.sh\n\n# Validate all code (ruff check, mypy)\n./scripts/validate.sh\n```\n\nBoth scripts must pass with no errors before code review.\n\n**PR Title Format:**\n\nPR titles must follow one of these formats:\n- `type: description` — e.g., `feat: add workflow serialization`\n- `[type] description` — e.g., `[feat] add workflow serialization`\n- `type-kebab-case` — e.g., `feat-workflow-serialization`\n\nValid types: `feat`, `fix`, `cookbook`, `test`, `refactor`, `chore`, `style`, `revert`, `release`\n\n**PR Description:**\n\nAlways follow the PR template in `.github/pull_request_template.md`. Include:\n- Summary of changes\n- Type of change (bug fix, new feature, etc.)\n- Completed checklist items\n- Any additional context\n\n---\n\n## GitHub Operations\n\n**Updating PR descriptions:**\n\nThe `gh pr edit` command may fail with GraphQL errors related to classic projects. Use the API directly instead:\n\n```bash\n# Update PR body\ngh api repos/agno-agi/agno/pulls/<PR_NUMBER> -X PATCH -f body=\"<PR_BODY>\"\n\n# Or with a file\ngh api repos/agno-agi/agno/pulls/<PR_NUMBER> -X PATCH -f body=\"$(cat /path/to/body.md)\"\n```\n\n---\n\n## Don't\n\n- Don't implement features without checking for a design doc first\n- Don't use f-strings for print lines where there are no variables\n- Don't use emojis in examples and print lines\n- Don't skip async variants of public methods\n- Don't push code without running `./scripts/format.sh` and `./scripts/validate.sh`\n- Don't submit a PR without a detailed PR description. Always follow the PR template provided in `.github/pull_request_template.md`.\n- Don't use `OpenAIChat` in cookbooks or examples — use `OpenAIResponses` instead\n- Don't use `gpt-4o` or `gpt-4o-mini` in cookbooks or examples — use `gpt-5.5` instead\n\n---\n\n## CI: Automated Code Review\n\nEvery 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.\n\nWhen 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.\"\n\nAgno-specific checks to always verify:\n- Both sync and async variants exist for all new public methods\n- No agent creation inside loops (agents should be reused)\n- CLAUDE.md coding patterns are followed\n- No f-strings for print lines where there are no variables\n","AGENTS.md":"# AGENTS.md — Agno\n\nInstructions for AI coding agents working on this codebase.\n\n---\n\n## Repository Structure\n\n```\n.\n├── libs/agno/agno/          # Core framework code\n├── cookbook/                # Examples, patterns and test cases (organized by topic)\n├── scripts/                 # Development and build scripts\n├── specs/                   # Design documents (symlinked, private)\n├── docs/                    # Documentation (symlinked, private)\n└── .cursorrules             # Coding patterns and conventions\n```\n\n---\n\n## Conductor Notes\n\nWhen working in Conductor, you can use the `.context/` directory for scratch notes or agent-to-agent handoff artifacts. This directory is gitignored.\n\n---\n\n## Setting Up Symlinks\n\nThe `specs/` and `docs/` directories are symlinked from external locations. For a fresh clone or new workspace, create these symlinks:\n\n```bash\nln -s ~/code/specs specs\nln -s ~/code/docs docs\n```\n\nThese contain private design documents and documentation that are not checked into the repository.\n\n---\n\n## Virtual Environments\n\nThis project uses two virtual environments:\n\n| Environment | Purpose | Setup |\n|-------------|---------|-------|\n| `.venv/` | Development: tests, formatting, validation | `./scripts/dev_setup.sh` |\n| `.venvs/demo/` | Cookbooks: has all demo dependencies | `./scripts/demo_setup.sh` |\n\n**Use `.venv`** for development tasks (`pytest`, `./scripts/format.sh`, `./scripts/validate.sh`).\n\n**Use `.venvs/demo`** for running cookbook examples.\n\n---\n\n## Testing Cookbooks\n\nApart from implementing features, your most important task will be to test and maintain the cookbooks in `cookbook/` directory.\n\n> See `cookbook/08_learning/` for the golden standard.\n\n### Quick Reference\n\n**Test Environment:**\n\n```bash\n# Virtual environment with all dependencies\n.venvs/demo/bin/python\n\n# Setup (if needed)\n./scripts/demo_setup.sh\n\n# Database (if needed)\n./cookbook/scripts/run_pgvector.sh\n```\n\n**Run a cookbook:**\n```bash\n.venvs/demo/bin/python cookbook/<folder>/<file>.py\n```\n\n### Expected Cookbook Structure\n\nEach cookbook folder should have the following files:\n- `README.md` — The README for the cookbook.\n- `TEST_LOG.md` — Test results log.\n\n### Testing Workflow\n\n**1. Before Testing**\n- Ensure the virtual environment exists (run `./scripts/demo_setup.sh` if needed)\n- Start any required services (e.g., `./cookbook/scripts/run_pgvector.sh`)\n\n**2. Running Tests**\n```bash\n# Run individual cookbook\n.venvs/demo/bin/python cookbook/<folder>/<file>.py\n\n# Tail output for long tests\n.venvs/demo/bin/python cookbook/<folder>/<file>.py 2>&1 | tail -100\n```\n\n**3. Updating TEST_LOG.md**\n\nAfter each test, update the cookbook's `TEST_LOG.md` with:\n- Test name and path\n- Status: PASS or FAIL\n- Brief description of what was tested\n- Any notable observations or issues\n\nFormat:\n```markdown\n### filename.py\n\n**Status:** PASS/FAIL\n\n**Description:** What the test does and what was observed.\n\n**Result:** Summary of success/failure.\n\n---\n```\n\n---\n\n## Code Locations\n\n| What | Where |\n|------|-------|\n| Core agent code | `libs/agno/agno/agent/` |\n| Teams | `libs/agno/agno/team/` |\n| Workflows | `libs/agno/agno/workflow/` |\n| Tools | `libs/agno/agno/tools/` |\n| Models | `libs/agno/agno/models/` |\n| Knowledge/RAG | `libs/agno/agno/knowledge/` |\n| Memory | `libs/agno/agno/memory/` |\n| Learning | `libs/agno/agno/learn/` |\n| Database adapters | `libs/agno/agno/db/` |\n| Vector databases | `libs/agno/agno/vectordb/` |\n| Tests | `libs/agno/tests/` |\n\n---\n\n## Coding Patterns\n\nSee `.cursorrules` for detailed patterns. Key rules:\n\n- **Never create agents in loops** — reuse them for performance\n- **Use output_schema** for structured responses\n- **PostgreSQL in production**, SQLite for dev only\n- **Start with single agent**, scale up only when needed\n- **Both sync and async** — all public methods need both variants\n\n---\n\n## Running Code\n\n**Running cookbooks:**\n```bash\n.venvs/demo/bin/python cookbook/<folder>/<file>.py\n```\n\n**Running tests:**\n```bash\nsource .venv/bin/activate\npytest libs/agno/tests/\n\n# Run a specific test file\npytest libs/agno/tests/unit/test_agent.py\n```\n\n---\n\n## When Implementing Features\n\n1. **Check for design doc** in `specs/` — if it exists, follow it\n2. **Look at existing patterns** — find similar code and follow conventions\n3. **Create a cookbook** — every pattern should have an example\n4. **Update implementation.md** — mark what's done\n\n---\n\n## Before Submitting Code\n\n**Always run these scripts before pushing code or creating a PR:**\n\n```bash\n# Activate the virtual environment first\nsource .venv/bin/activate\n\n# Format all code (ruff format)\n./scripts/format.sh\n\n# Validate all code (ruff check, mypy)\n./scripts/validate.sh\n```\n\nBoth scripts must pass with no errors before code review.\n\n**PR Title Format:**\n\nPR titles must follow one of these formats:\n- `type: description` — e.g., `feat: add workflow serialization`\n- `[type] description` — e.g., `[feat] add workflow serialization`\n- `type-kebab-case` — e.g., `feat-workflow-serialization`\n\nValid types: `feat`, `fix`, `cookbook`, `test`, `refactor`, `chore`, `style`, `revert`, `release`\n\n**PR Description:**\n\nAlways follow the PR template in `.github/pull_request_template.md`. Include:\n- Summary of changes\n- Type of change (bug fix, new feature, etc.)\n- Completed checklist items\n- Any additional context\n\n---\n\n## GitHub Operations\n\n**Updating PR descriptions:**\n\nThe `gh pr edit` command may fail with GraphQL errors related to classic projects. Use the API directly instead:\n\n```bash\n# Update PR body\ngh api repos/agno-agi/agno/pulls/<PR_NUMBER> -X PATCH -f body=\"<PR_BODY>\"\n\n# Or with a file\ngh api repos/agno-agi/agno/pulls/<PR_NUMBER> -X PATCH -f body=\"$(cat /path/to/body.md)\"\n```\n\n---\n\n## Don't\n\n- Don't implement features without checking for a design doc first\n- Don't use f-strings for print lines where there are no variables\n- Don't use emojis in examples and print lines\n- Don't skip async variants of public methods\n- Don't push code without running `./scripts/format.sh` and `./scripts/validate.sh`\n- Don't submit a PR without a detailed PR description. Always follow the PR template provided in `.github/pull_request_template.md`.\n",".cursorrules":"You are an expert in Python, Agno framework, and AI agent development.\n\nCore Rules\n- NEVER create agents in loops - reuse them for performance\n- Always use output_schema for structured responses\n- PostgreSQL in production, SQLite for dev only\n- Start with single agent, scale up only when needed\n\nDocumentation:\n- Don't use f-strings for print lines where there are no variables to format.\n- Don't use emojis in examples and print lines\n\nBasic Agent (start here):\n```python\nfrom agno.agent import Agent\nfrom agno.models.openai import OpenAIResponses\n\nagent = Agent(\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    instructions=\"You are a helpful assistant\",\n    markdown=True,\n)\nagent.print_response(\"Your query\", stream=True)\n```\n\nAgent with Tools:\n```python\nfrom agno.tools.websearch import WebSearchTools\n\nagent = Agent(\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    tools=[WebSearchTools()],\n    instructions=\"Search the web for information\",\n)\n```\n\nCRITICAL: Agent Reuse Performance\n```python\n# WRONG - Recreates agent every time (significant overhead)\nfor query in queries:\n    agent = Agent(...)  # DON'T DO THIS\n    \n# CORRECT - Create once, reuse\nagent = Agent(...)\nfor query in queries:\n    agent.run(query)\n```\n\nWhen to Use Each Pattern\n\nSingle Agent (90% of use cases):\n- One clear task or domain\n- Can be solved with tools + instructions\n- Example: Search, analyze, generate content\n\nTeam (autonomous coordination):\n- Multiple specialized agents with different expertise\n- Agents decide who does what via LLM\n- Complex tasks requiring multiple perspectives\n- Example: Research + Analysis + Writing\n\nWorkflow (programmatic control):\n- Sequential steps with clear flow\n- Need conditional logic or branching\n- Full control over execution order\n- Example: Extract → Transform → Load pipelines\n\nTeam Pattern:\n```python\nfrom agno.team.team import Team\n\nweb_agent = Agent(\n    name=\"Researcher\",\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    tools=[WebSearchTools()],\n)\n\nwriter_agent = Agent(\n    name=\"Writer\",\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n)\n\nteam = Team(\n    members=[web_agent, writer_agent],\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    instructions=\"Research and write articles\",\n)\n```\n\nWorkflow Pattern:\n```python\nfrom agno.workflow.workflow import Workflow\nfrom agno.db.sqlite import SqliteDb\n\n# Define agents first (researcher, writer)\nasync def blog_workflow(session_state, topic: str):\n    # Step 1: Research\n    research = await researcher.arun(topic)\n    \n    # Step 2: Write\n    article = await writer.arun(research.content)\n    \n    return article\n\nworkflow = Workflow(\n    name=\"Blog Generator\",\n    steps=blog_workflow,\n    db=SqliteDb(db_file=\"tmp/workflow.db\"),\n)\n```\n\nKnowledge/RAG:\n```python\nfrom agno.knowledge.knowledge import Knowledge\nfrom agno.vectordb.lancedb import LanceDb, SearchType\nfrom agno.knowledge.embedder.openai import OpenAIEmbedder\n\nknowledge = Knowledge(\n    vector_db=LanceDb(\n        uri=\"tmp/lancedb\",\n        table_name=\"knowledge_base\",\n        search_type=SearchType.hybrid,\n        embedder=OpenAIEmbedder(id=\"text-embedding-3-small\"),\n    ),\n)\n\nagent = Agent(\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    knowledge=knowledge,\n    search_knowledge=True,  # Critical: enables agentic RAG\n    instructions=\"Use knowledge base, cite sources\"\n)\n```\n\nChat History:\n```python\nagent = Agent(\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    db=SqliteDb(db_file=\"tmp/agents.db\"),\n    user_id=\"user-123\",\n    add_history_to_context=True,  # Adds previous messages\n    num_history_runs=3,\n)\n```\n\nStructured Output:\n```python\nfrom pydantic import BaseModel\n\nclass Result(BaseModel):\n    summary: str\n    findings: list[str]\n\nagent = Agent(\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    output_schema=Result,\n)\nresult: Result = agent.run(query).content\n```\n\nAgentOS Production:\n```python\nfrom agno.os import AgentOS\nfrom agno.db.postgres import PostgresDb\n\nagent_os = AgentOS(\n    agents=[agent],\n    db=PostgresDb(db_url=os.getenv(\"DATABASE_URL\")),\n)\napp = agent_os.get_app()\n```\n\nCommon Mistakes\n- Creating agents in loops (massive performance hit)\n- Using Team when single agent would work\n- Forgetting search_knowledge=True with knowledge\n- Using SQLite in production\n- Not adding history when context matters\n- Missing output_schema validation\n\nProduction\n- Use PostgresDb not SqliteDb\n- Set show_tool_calls=False, debug_mode=False\n- Wrap agent.run() in try-except\n\nDocs: https://docs.agno.com\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md — Agno\n\nInstructions for Claude Code when working on this codebase.\n\n---\n\n## Repository Structure\n\n```\n.\n├── libs/agno/agno/          # Core framework code\n├── cookbook/                # Examples, patterns and test cases (organized by topic)\n├── scripts/                 # Development and build scripts\n├── specs/                   # Design documents (symlinked, private)\n├── docs/                    # Documentation (symlinked, private)\n└── .cursorrules             # Coding patterns and conventions\n```\n\n---\n\n## Conductor Notes\n\nWhen working in Conductor, you can use the `.context/` directory for scratch notes or agent-to-agent handoff artifacts. This directory is gitignored.\n\n---\n\n## Setting Up Symlinks\n\nThe `specs/` and `docs/` directories are symlinked from external locations. For a fresh clone or new workspace, create these symlinks:\n\n```bash\nln -s ~/code/specs specs\nln -s ~/code/docs docs\n```\n\nThese contain private design documents and documentation that are not checked into the repository.\n\n---\n\n## Virtual Environments\n\nThis project uses two virtual environments:\n\n| Environment | Purpose | Setup |\n|-------------|---------|-------|\n| `.venv/` | Development: tests, formatting, validation | `./scripts/dev_setup.sh` |\n| `.venvs/demo/` | Cookbooks: has all demo dependencies | `./scripts/demo_setup.sh` |\n\n**Use `.venv`** for development tasks (`pytest`, `./scripts/format.sh`, `./scripts/validate.sh`).\n\n**Use `.venvs/demo`** for running cookbook examples.\n\n---\n\n## Testing Cookbooks\n\nApart from implementing features, your most important task will be to test and maintain the cookbooks in `cookbook/` directory.\n\n> See `cookbook/08_learning/` for the golden standard.\n\n### Quick Reference\n\n**Test Environment:**\n\n```bash\n# Virtual environment with all dependencies\n.venvs/demo/bin/python\n\n# Setup (if needed)\n./scripts/demo_setup.sh\n\n# Database (if needed)\n./cookbook/scripts/run_pgvector.sh\n```\n\n**Run a cookbook:**\n```bash\n.venvs/demo/bin/python cookbook/<folder>/<file>.py\n```\n\n### Expected Cookbook Structure\n\nEach cookbook folder should have the following files:\n- `README.md` — The README for the cookbook.\n- `TEST_LOG.md` — Test results log.\n\n### Testing Workflow\n\n**1. Before Testing**\n- Ensure the virtual environment exists (run `./scripts/demo_setup.sh` if needed)\n- Start any required services (e.g., `./cookbook/scripts/run_pgvector.sh`)\n\n**2. Running Tests**\n```bash\n# Run individual cookbook\n.venvs/demo/bin/python cookbook/<folder>/<file>.py\n\n# Tail output for long tests\n.venvs/demo/bin/python cookbook/<folder>/<file>.py 2>&1 | tail -100\n```\n\n**3. Updating TEST_LOG.md**\n\nAfter each test, update the cookbook's `TEST_LOG.md` with:\n- Test name and path\n- Status: PASS or FAIL\n- Brief description of what was tested\n- Any notable observations or issues\n\nFormat:\n```markdown\n### filename.py\n\n**Status:** PASS/FAIL\n\n**Description:** What the test does and what was observed.\n\n**Result:** Summary of success/failure.\n\n---\n```\n\n---\n\n## Code Locations\n\n| What | Where |\n|------|-------|\n| Core agent code | `libs/agno/agno/agent/` |\n| Teams | `libs/agno/agno/team/` |\n| Workflows | `libs/agno/agno/workflow/` |\n| Tools | `libs/agno/agno/tools/` |\n| Models | `libs/agno/agno/models/` |\n| Knowledge/RAG | `libs/agno/agno/knowledge/` |\n| Memory | `libs/agno/agno/memory/` |\n| Learning | `libs/agno/agno/learn/` |\n| Database adapters | `libs/agno/agno/db/` |\n| Vector databases | `libs/agno/agno/vectordb/` |\n| Tests | `libs/agno/tests/` |\n\n---\n\n## Coding Patterns\n\nSee `.cursorrules` for detailed patterns. Key rules:\n\n- **Never create agents in loops** — reuse them for performance\n- **Use output_schema** for structured responses\n- **PostgreSQL in production**, SQLite for dev only\n- **Start with single agent**, scale up only when needed\n- **Both sync and async** — all public methods need both variants\n\n---\n\n## Running Code\n\n**Running cookbooks:**\n```bash\n.venvs/demo/bin/python cookbook/<folder>/<file>.py\n```\n\n**Running tests:**\n```bash\nsource .venv/bin/activate\npytest libs/agno/tests/\n\n# Run a specific test file\npytest libs/agno/tests/unit/test_agent.py\n```\n\n---\n\n## When Implementing Features\n\n1. **Check for design doc** in `specs/` — if it exists, follow it\n2. **Look at existing patterns** — find similar code and follow conventions\n3. **Create a cookbook** — every pattern should have an example\n4. **Update implementation.md** — mark what's done\n\n---\n\n## Before Submitting Code\n\n**Always run these scripts before pushing code or creating a PR:**\n\n```bash\n# Activate the virtual environment first\nsource .venv/bin/activate\n\n# Format all code (ruff format)\n./scripts/format.sh\n\n# Validate all code (ruff check, mypy)\n./scripts/validate.sh\n```\n\nBoth scripts must pass with no errors before code review.\n\n**PR Title Format:**\n\nPR titles must follow one of these formats:\n- `type: description` — e.g., `feat: add workflow serialization`\n- `[type] description` — e.g., `[feat] add workflow serialization`\n- `type-kebab-case` — e.g., `feat-workflow-serialization`\n\nValid types: `feat`, `fix`, `cookbook`, `test`, `refactor`, `chore`, `style`, `revert`, `release`\n\n**PR Description:**\n\nAlways follow the PR template in `.github/pull_request_template.md`. Include:\n- Summary of changes\n- Type of change (bug fix, new feature, etc.)\n- Completed checklist items\n- Any additional context\n\n---\n\n## GitHub Operations\n\n**Updating PR descriptions:**\n\nThe `gh pr edit` command may fail with GraphQL errors related to classic projects. Use the API directly instead:\n\n```bash\n# Update PR body\ngh api repos/agno-agi/agno/pulls/<PR_NUMBER> -X PATCH -f body=\"<PR_BODY>\"\n\n# Or with a file\ngh api repos/agno-agi/agno/pulls/<PR_NUMBER> -X PATCH -f body=\"$(cat /path/to/body.md)\"\n```\n\n---\n\n## Don't\n\n- Don't implement features without checking for a design doc first\n- Don't use f-strings for print lines where there are no variables\n- Don't use emojis in examples and print lines\n- Don't skip async variants of public methods\n- Don't push code without running `./scripts/format.sh` and `./scripts/validate.sh`\n- Don't submit a PR without a detailed PR description. Always follow the PR template provided in `.github/pull_request_template.md`.\n- Don't use `OpenAIChat` in cookbooks or examples — use `OpenAIResponses` instead\n- Don't use `gpt-4o` or `gpt-4o-mini` in cookbooks or examples — use `gpt-5.5` instead\n\n---\n\n## CI: Automated Code Review\n\nEvery 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.\n\nWhen 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.\"\n\nAgno-specific checks to always verify:\n- Both sync and async variants exist for all new public methods\n- No agent creation inside loops (agents should be reused)\n- CLAUDE.md coding patterns are followed\n- No f-strings for print lines where there are no variables\n","category":"root","tokens":1770},{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md — Agno\n\nInstructions for AI coding agents working on this codebase.\n\n---\n\n## Repository Structure\n\n```\n.\n├── libs/agno/agno/          # Core framework code\n├── cookbook/                # Examples, patterns and test cases (organized by topic)\n├── scripts/                 # Development and build scripts\n├── specs/                   # Design documents (symlinked, private)\n├── docs/                    # Documentation (symlinked, private)\n└── .cursorrules             # Coding patterns and conventions\n```\n\n---\n\n## Conductor Notes\n\nWhen working in Conductor, you can use the `.context/` directory for scratch notes or agent-to-agent handoff artifacts. This directory is gitignored.\n\n---\n\n## Setting Up Symlinks\n\nThe `specs/` and `docs/` directories are symlinked from external locations. For a fresh clone or new workspace, create these symlinks:\n\n```bash\nln -s ~/code/specs specs\nln -s ~/code/docs docs\n```\n\nThese contain private design documents and documentation that are not checked into the repository.\n\n---\n\n## Virtual Environments\n\nThis project uses two virtual environments:\n\n| Environment | Purpose | Setup |\n|-------------|---------|-------|\n| `.venv/` | Development: tests, formatting, validation | `./scripts/dev_setup.sh` |\n| `.venvs/demo/` | Cookbooks: has all demo dependencies | `./scripts/demo_setup.sh` |\n\n**Use `.venv`** for development tasks (`pytest`, `./scripts/format.sh`, `./scripts/validate.sh`).\n\n**Use `.venvs/demo`** for running cookbook examples.\n\n---\n\n## Testing Cookbooks\n\nApart from implementing features, your most important task will be to test and maintain the cookbooks in `cookbook/` directory.\n\n> See `cookbook/08_learning/` for the golden standard.\n\n### Quick Reference\n\n**Test Environment:**\n\n```bash\n# Virtual environment with all dependencies\n.venvs/demo/bin/python\n\n# Setup (if needed)\n./scripts/demo_setup.sh\n\n# Database (if needed)\n./cookbook/scripts/run_pgvector.sh\n```\n\n**Run a cookbook:**\n```bash\n.venvs/demo/bin/python cookbook/<folder>/<file>.py\n```\n\n### Expected Cookbook Structure\n\nEach cookbook folder should have the following files:\n- `README.md` — The README for the cookbook.\n- `TEST_LOG.md` — Test results log.\n\n### Testing Workflow\n\n**1. Before Testing**\n- Ensure the virtual environment exists (run `./scripts/demo_setup.sh` if needed)\n- Start any required services (e.g., `./cookbook/scripts/run_pgvector.sh`)\n\n**2. Running Tests**\n```bash\n# Run individual cookbook\n.venvs/demo/bin/python cookbook/<folder>/<file>.py\n\n# Tail output for long tests\n.venvs/demo/bin/python cookbook/<folder>/<file>.py 2>&1 | tail -100\n```\n\n**3. Updating TEST_LOG.md**\n\nAfter each test, update the cookbook's `TEST_LOG.md` with:\n- Test name and path\n- Status: PASS or FAIL\n- Brief description of what was tested\n- Any notable observations or issues\n\nFormat:\n```markdown\n### filename.py\n\n**Status:** PASS/FAIL\n\n**Description:** What the test does and what was observed.\n\n**Result:** Summary of success/failure.\n\n---\n```\n\n---\n\n## Code Locations\n\n| What | Where |\n|------|-------|\n| Core agent code | `libs/agno/agno/agent/` |\n| Teams | `libs/agno/agno/team/` |\n| Workflows | `libs/agno/agno/workflow/` |\n| Tools | `libs/agno/agno/tools/` |\n| Models | `libs/agno/agno/models/` |\n| Knowledge/RAG | `libs/agno/agno/knowledge/` |\n| Memory | `libs/agno/agno/memory/` |\n| Learning | `libs/agno/agno/learn/` |\n| Database adapters | `libs/agno/agno/db/` |\n| Vector databases | `libs/agno/agno/vectordb/` |\n| Tests | `libs/agno/tests/` |\n\n---\n\n## Coding Patterns\n\nSee `.cursorrules` for detailed patterns. Key rules:\n\n- **Never create agents in loops** — reuse them for performance\n- **Use output_schema** for structured responses\n- **PostgreSQL in production**, SQLite for dev only\n- **Start with single agent**, scale up only when needed\n- **Both sync and async** — all public methods need both variants\n\n---\n\n## Running Code\n\n**Running cookbooks:**\n```bash\n.venvs/demo/bin/python cookbook/<folder>/<file>.py\n```\n\n**Running tests:**\n```bash\nsource .venv/bin/activate\npytest libs/agno/tests/\n\n# Run a specific test file\npytest libs/agno/tests/unit/test_agent.py\n```\n\n---\n\n## When Implementing Features\n\n1. **Check for design doc** in `specs/` — if it exists, follow it\n2. **Look at existing patterns** — find similar code and follow conventions\n3. **Create a cookbook** — every pattern should have an example\n4. **Update implementation.md** — mark what's done\n\n---\n\n## Before Submitting Code\n\n**Always run these scripts before pushing code or creating a PR:**\n\n```bash\n# Activate the virtual environment first\nsource .venv/bin/activate\n\n# Format all code (ruff format)\n./scripts/format.sh\n\n# Validate all code (ruff check, mypy)\n./scripts/validate.sh\n```\n\nBoth scripts must pass with no errors before code review.\n\n**PR Title Format:**\n\nPR titles must follow one of these formats:\n- `type: description` — e.g., `feat: add workflow serialization`\n- `[type] description` — e.g., `[feat] add workflow serialization`\n- `type-kebab-case` — e.g., `feat-workflow-serialization`\n\nValid types: `feat`, `fix`, `cookbook`, `test`, `refactor`, `chore`, `style`, `revert`, `release`\n\n**PR Description:**\n\nAlways follow the PR template in `.github/pull_request_template.md`. Include:\n- Summary of changes\n- Type of change (bug fix, new feature, etc.)\n- Completed checklist items\n- Any additional context\n\n---\n\n## GitHub Operations\n\n**Updating PR descriptions:**\n\nThe `gh pr edit` command may fail with GraphQL errors related to classic projects. Use the API directly instead:\n\n```bash\n# Update PR body\ngh api repos/agno-agi/agno/pulls/<PR_NUMBER> -X PATCH -f body=\"<PR_BODY>\"\n\n# Or with a file\ngh api repos/agno-agi/agno/pulls/<PR_NUMBER> -X PATCH -f body=\"$(cat /path/to/body.md)\"\n```\n\n---\n\n## Don't\n\n- Don't implement features without checking for a design doc first\n- Don't use f-strings for print lines where there are no variables\n- Don't use emojis in examples and print lines\n- Don't skip async variants of public methods\n- Don't push code without running `./scripts/format.sh` and `./scripts/validate.sh`\n- Don't submit a PR without a detailed PR description. Always follow the PR template provided in `.github/pull_request_template.md`.\n","category":"root","tokens":1544},{"name":".cursorrules","path":".cursorrules","title":".cursorrules","content":"You are an expert in Python, Agno framework, and AI agent development.\n\nCore Rules\n- NEVER create agents in loops - reuse them for performance\n- Always use output_schema for structured responses\n- PostgreSQL in production, SQLite for dev only\n- Start with single agent, scale up only when needed\n\nDocumentation:\n- Don't use f-strings for print lines where there are no variables to format.\n- Don't use emojis in examples and print lines\n\nBasic Agent (start here):\n```python\nfrom agno.agent import Agent\nfrom agno.models.openai import OpenAIResponses\n\nagent = Agent(\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    instructions=\"You are a helpful assistant\",\n    markdown=True,\n)\nagent.print_response(\"Your query\", stream=True)\n```\n\nAgent with Tools:\n```python\nfrom agno.tools.websearch import WebSearchTools\n\nagent = Agent(\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    tools=[WebSearchTools()],\n    instructions=\"Search the web for information\",\n)\n```\n\nCRITICAL: Agent Reuse Performance\n```python\n# WRONG - Recreates agent every time (significant overhead)\nfor query in queries:\n    agent = Agent(...)  # DON'T DO THIS\n    \n# CORRECT - Create once, reuse\nagent = Agent(...)\nfor query in queries:\n    agent.run(query)\n```\n\nWhen to Use Each Pattern\n\nSingle Agent (90% of use cases):\n- One clear task or domain\n- Can be solved with tools + instructions\n- Example: Search, analyze, generate content\n\nTeam (autonomous coordination):\n- Multiple specialized agents with different expertise\n- Agents decide who does what via LLM\n- Complex tasks requiring multiple perspectives\n- Example: Research + Analysis + Writing\n\nWorkflow (programmatic control):\n- Sequential steps with clear flow\n- Need conditional logic or branching\n- Full control over execution order\n- Example: Extract → Transform → Load pipelines\n\nTeam Pattern:\n```python\nfrom agno.team.team import Team\n\nweb_agent = Agent(\n    name=\"Researcher\",\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    tools=[WebSearchTools()],\n)\n\nwriter_agent = Agent(\n    name=\"Writer\",\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n)\n\nteam = Team(\n    members=[web_agent, writer_agent],\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    instructions=\"Research and write articles\",\n)\n```\n\nWorkflow Pattern:\n```python\nfrom agno.workflow.workflow import Workflow\nfrom agno.db.sqlite import SqliteDb\n\n# Define agents first (researcher, writer)\nasync def blog_workflow(session_state, topic: str):\n    # Step 1: Research\n    research = await researcher.arun(topic)\n    \n    # Step 2: Write\n    article = await writer.arun(research.content)\n    \n    return article\n\nworkflow = Workflow(\n    name=\"Blog Generator\",\n    steps=blog_workflow,\n    db=SqliteDb(db_file=\"tmp/workflow.db\"),\n)\n```\n\nKnowledge/RAG:\n```python\nfrom agno.knowledge.knowledge import Knowledge\nfrom agno.vectordb.lancedb import LanceDb, SearchType\nfrom agno.knowledge.embedder.openai import OpenAIEmbedder\n\nknowledge = Knowledge(\n    vector_db=LanceDb(\n        uri=\"tmp/lancedb\",\n        table_name=\"knowledge_base\",\n        search_type=SearchType.hybrid,\n        embedder=OpenAIEmbedder(id=\"text-embedding-3-small\"),\n    ),\n)\n\nagent = Agent(\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    knowledge=knowledge,\n    search_knowledge=True,  # Critical: enables agentic RAG\n    instructions=\"Use knowledge base, cite sources\"\n)\n```\n\nChat History:\n```python\nagent = Agent(\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    db=SqliteDb(db_file=\"tmp/agents.db\"),\n    user_id=\"user-123\",\n    add_history_to_context=True,  # Adds previous messages\n    num_history_runs=3,\n)\n```\n\nStructured Output:\n```python\nfrom pydantic import BaseModel\n\nclass Result(BaseModel):\n    summary: str\n    findings: list[str]\n\nagent = Agent(\n    model=OpenAIResponses(id=\"gpt-5.5\"),\n    output_schema=Result,\n)\nresult: Result = agent.run(query).content\n```\n\nAgentOS Production:\n```python\nfrom agno.os import AgentOS\nfrom agno.db.postgres import PostgresDb\n\nagent_os = AgentOS(\n    agents=[agent],\n    db=PostgresDb(db_url=os.getenv(\"DATABASE_URL\")),\n)\napp = agent_os.get_app()\n```\n\nCommon Mistakes\n- Creating agents in loops (massive performance hit)\n- Using Team when single agent would work\n- Forgetting search_knowledge=True with knowledge\n- Using SQLite in production\n- Not adding history when context matters\n- Missing output_schema validation\n\nProduction\n- Use PostgresDb not SqliteDb\n- Set show_tool_calls=False, debug_mode=False\n- Wrap agent.run() in try-except\n\nDocs: https://docs.agno.com\n","category":"root","tokens":1111}]}