agno

Agno 技能

全面协助 Agno 开发。Agno 是一个现代 AI Agent 框架，可用于构建支持 MCP 集成、工作流编排和 AgentOS 运行时的生产级多 Agent 系统。

何时使用此技能

在以下情况下应触发此技能：

• 构建 AI Agent，并为其添加工具、记忆和结构化输出
• 创建多 Agent 团队，实现基于角色的任务委派与协作
• 实现工作流，支持条件分支、循环和异步执行
• 集成 MCP 服务（stdio、SSE 或 Streamable HTTP 传输方式）
• 部署 AgentOS，并使用自定义 FastAPI 应用、JWT 中间件或数据库后端
• 使用知识库进行 RAG 和文档处理
• 使用调试模式和遥测调试 Agent 行为
• 使用指数退避、重试和速率限制优化 Agent 性能

核心概念

核心架构

• Agent：单个自主 AI 单元，包含模型、工具、指令以及可选的记忆/知识
• Team：由多个 Agent 组成的集合，通过基于角色的任务委派协作完成任务
• Workflow：支持条件分支、循环和并行执行的多步骤编排
• AgentOS：基于 FastAPI 的运行时，可将 Agent 部署为生产级 API

MCP 集成

• MCPTools：通过 stdio、SSE 或 Streamable HTTP 连接到单个 MCP 服务
• MultiMCPTools：同时连接到多个 MCP 服务
• 传输类型：stdio（本地进程）、SSE（服务器发送事件）、Streamable HTTP（生产环境）

记忆与知识

• 会话记忆：存储在 PostgreSQL、SQLite 或云存储（GCS）中的对话状态
• 知识库：由 RAG 驱动、使用向量嵌入的文档检索
• 用户记忆：跨会话持久保存的用户专属记忆

快速参考

1. 使用工具的基础 Agent

from agno.agent import Agent
from agno.tools.duckduckgo import DuckDuckGoTools

agent = Agent(
    tools=[DuckDuckGoTools()],
    markdown=True,
)

agent.print_response("Search for the latest AI news", stream=True)

2. 使用结构化输出的 Agent

from agno.agent import Agent
from pydantic import BaseModel, Field

class MovieScript(BaseModel):
    name: str = Field(..., description="Movie title")
    genre: str = Field(..., description="Movie genre")
    storyline: str = Field(..., description="3 sentence storyline")

agent = Agent(
    description="You help people write movie scripts.",
    output_schema=MovieScript,
)

result = agent.run("Write a sci-fi thriller")
print(result.content.name)  # Access structured output

3. MCP 服务集成（stdio）

import asyncio
from agno.agent import Agent
from agno.tools.mcp import MCPTools

async def run_agent(message: str) -> None:
    mcp_tools = MCPTools(command="uvx mcp-server-git")
    await mcp_tools.connect()

    try:
        agent = Agent(tools=[mcp_tools])
        await agent.aprint_response(message, stream=True)
    finally:
        await mcp_tools.close()

asyncio.run(run_agent("What is the license for this project?"))

4. 多个 MCP 服务

import asyncio
import os
from agno.agent import Agent
from agno.tools.mcp import MultiMCPTools

async def run_agent(message: str) -> None:
    env = {
        **os.environ,
        "GOOGLE_MAPS_API_KEY": os.getenv("GOOGLE_MAPS_API_KEY"),
    }

    mcp_tools = MultiMCPTools(
        commands=[
            "npx -y @openbnb/mcp-server-airbnb --ignore-robots-txt",
            "npx -y @modelcontextprotocol/server-google-maps",
        ],
        env=env,
    )
    await mcp_tools.connect()

    try:
        agent = Agent(tools=[mcp_tools], markdown=True)
        await agent.aprint_response(message, stream=True)
    finally:
        await mcp_tools.close()

5. 通过角色委派实现的多 Agent 团队

from agno.agent import Agent
from agno.team import Team
from agno.tools.duckduckgo import DuckDuckGoTools
from agno.tools.hackernews import HackerNewsTools

research_agent = Agent(
    name="Research Specialist",
    role="Gather information on topics",
    tools=[DuckDuckGoTools()],
    instructions=["Find comprehensive information", "Cite sources"],
)

news_agent = Agent(
    name="News Analyst",
    role="Analyze tech news",
    tools=[HackerNewsTools()],
    instructions=["Focus on trending topics", "Summarize key points"],
)

team = Team(
    members=[research_agent, news_agent],
    instructions=["Delegate research tasks to appropriate agents"],
)

team.print_response("Research AI trends and latest HN discussions", stream=True)

6. 带条件分支的工作流

from agno.agent import Agent
from agno.workflow.workflow import Workflow
from agno.workflow.router import Router
from agno.workflow.step import Step
from agno.tools.duckduckgo import DuckDuckGoTools
from agno.tools.hackernews import HackerNewsTools

simple_researcher = Agent(
    name="Simple Researcher",
    tools=[DuckDuckGoTools()],
)

deep_researcher = Agent(
    name="Deep Researcher",
    tools=[HackerNewsTools()],
)

workflow = Workflow(
    steps=[
        Router(
            routes={
                "simple_topics": Step(agent=simple_researcher),
                "complex_topics": Step(agent=deep_researcher),
            }
        )
    ]
)

workflow.run("Research quantum computing")

7. 使用数据库存储会话的 Agent

from agno.agent import Agent
from agno.db.postgres import PostgresDb

db = PostgresDb(
    db_url="postgresql://user:pass@localhost:5432/agno",
    schema="agno_sessions"
)

agent = Agent(
    db=db,
    session_id="user-123",  # Persistent session
    add_history_to_messages=True,
)

# Conversations are automatically saved and restored
agent.print_response("Remember my favorite color is blue")
agent.print_response("What's my favorite color?")  # Will remember

8. 使用自定义 FastAPI 应用的 AgentOS

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

# Custom FastAPI app
app = FastAPI(title="Custom App")

@app.get("/health")
def health_check():
    return {"status": "healthy"}

# Add AgentOS routes
agent_os = AgentOS(
    agents=[Agent(id="assistant", model=OpenAIChat(id="gpt-5-mini"))],
    base_app=app  # Merge with custom app
)

if __name__ == "__main__":
    agent_os.serve(app="custom_app:app", reload=True)

9. 使用调试模式的 Agent

from agno.agent import Agent
from agno.tools.hackernews import HackerNewsTools

agent = Agent(
    tools=[HackerNewsTools()],
    debug_mode=True,  # Enable detailed logging
    # debug_level=2,  # More verbose output
)

# See detailed logs of:
# - Messages sent to model
# - Tool calls and results
# - Token usage and timing
agent.print_response("Get top HN stories")

10. 带输入架构验证的工作流

from typing import List
from agno.agent import Agent
from agno.workflow.workflow import Workflow
from agno.workflow.step import Step
from pydantic import BaseModel, Field

class ResearchTopic(BaseModel):
    """Structured research topic with specific requirements"""
    topic: str
    focus_areas: List[str] = Field(description="Specific areas to focus on")
    target_audience: str = Field(description="Who this research is for")
    sources_required: int = Field(description="Number of sources needed", default=5)

workflow = Workflow(
    input_schema=ResearchTopic,  # Validate inputs
    steps=[
        Step(agent=Agent(instructions=["Research based on focus areas"]))
    ]
)

# This will validate the input structure
workflow.run({
    "topic": "AI Safety",
    "focus_areas": ["alignment", "interpretability"],
    "target_audience": "researchers",
    "sources_required": 10
})

参考文件

此技能在 references/ 中包含全面的文档：

agentos.md（22 页）

• MCP 服务集成（stdio、SSE、Streamable HTTP）
• 多个 MCP 服务连接
• 自定义 FastAPI 应用集成
• JWT 中间件与身份验证
• AgentOS 生命周期管理
• 遥测与监控

agents.md（834 页）

• Agent 的创建与配置
• 工具集成（DuckDuckGo、HackerNews、Pandas、PostgreSQL、Wikipedia）
• 使用 Pydantic 实现结构化输出
• 记忆管理（会话、用户、知识）
• 使用调试模式进行调试
• 人机协作模式
• 多模态 Agent（音频、视频、图像）
• 数据库后端（PostgreSQL、SQLite、GCS）
• 状态管理与会话持久化

examples.md（188 页）

• 工作流模式（条件分支、循环、路由器）
• 团队协作示例
• 异步流式工作流
• 音频/视频处理团队
• 图像生成管线
• 多步骤编排
• 输入架构验证

getting_started.md

• 安装与设置
• 第一个 Agent 示例
• MCP 服务快速入门
• 常见模式与最佳实践

integration.md

• 第三方集成
• API 连接
• 自定义工具创建
• 数据库设置

migration.md

• 跨版本升级
• 重大变更与迁移指南
• 弃用功能

other.md

• 高级主题
• 性能优化
• 生产环境部署

使用此技能

初学者

从 getting_started.md 开始，了解：

• 使用 Agent() 创建 Agent 的基础知识
• 添加用于网页搜索、数据库等的工具
• 使用 .print_response() 或 .run() 运行 Agent
• 了解 Agent、Team 和 Workflow 之间的区别

快速入门模式：

from agno.agent import Agent
from agno.tools.duckduckgo import DuckDuckGoTools

agent = Agent(tools=[DuckDuckGoTools()])
agent.print_response("Your question here")

中级用户

阅读 agents.md 和 examples.md，了解：

• 通过角色委派组建多 Agent 团队
• 集成 MCP 服务（通过 stdio 使用本地工具）
• 使用条件逻辑编排工作流
• 使用数据库持久化会话
• 使用 Pydantic 模型生成结构化输出

团队模式：

from agno.team import Team

team = Team(
    members=[researcher, analyst, writer],
    instructions=["Delegate tasks based on agent roles"]
)

高级用户

深入阅读 agentos.md，了解：

• 使用自定义 FastAPI 应用部署 AgentOS
• 编排多个 MCP 服务
• 使用 JWT 中间件进行生产环境身份验证
• 自定义生命周期管理
• 使用指数退避进行性能调优
• 集成遥测和监控

AgentOS 模式：

from agno.os import AgentOS

agent_os = AgentOS(
    agents=[agent1, agent2],
    db=PostgresDb(...),
    base_app=custom_fastapi_app
)
agent_os.serve()

导航提示

1. 查找示例？ → 首先查看 examples.md，了解真实场景中的模式
2. 需要 API 详情？ → 在 agents.md 中查找类的引用和参数
3. 要部署到生产环境？ → 阅读 agentos.md，了解 AgentOS 设置
4. 要集成外部工具？ → 查看 integration.md，了解 MCP 和自定义工具
5. 要调试问题？ → 启用 debug_mode=True 并查看日志

常见模式

模式：MCP 服务连接生命周期

async def run_with_mcp():
    mcp_tools = MCPTools(command="uvx mcp-server-git")
    await mcp_tools.connect()  # Always connect before use

    try:
        agent = Agent(tools=[mcp_tools])
        await agent.aprint_response("Your query")
    finally:
        await mcp_tools.close()  # Always close when done

模式：使用数据库持久化会话

from agno.agent import Agent
from agno.db.postgres import PostgresDb

db = PostgresDb(db_url="postgresql://...")

agent = Agent(
    db=db,
    session_id="unique-user-id",
    add_history_to_messages=True,  # Include conversation history
)

模式：条件工作流路由

from agno.workflow.router import Router

workflow = Workflow(
    steps=[
        Router(
            routes={
                "route_a": Step(agent=agent_a),
                "route_b": Step(agent=b),
            }
        )
    ]
)

资源

官方链接

• 文档：https://docs.agno.com
• GitHub：https://github.com/agno-agi/agno
• 示例：https://github.com/agno-agi/agno/tree/main/cookbook

需要牢记的关键概念

• 始终关闭 MCP 连接：使用 try/finally 代码块或异步上下文管理器
• 启用调试模式以排查问题：debug_mode=True 会显示详细的执行日志
• 使用结构化输出来确保可靠性：使用 output_schema= 定义 Pydantic 模式
• 使用数据库持久化会话：生产环境中的 Agent 可使用 PostgreSQL 或 SQLite
• 按需禁用遥测：设置 AGNO_TELEMETRY=false 或 telemetry=False

scripts/

在此添加用于常见自动化任务的辅助脚本。

assets/

在此添加模板、样板代码或示例项目。

备注

• 此技能根据 Agno 官方文档自动生成
• 参考文件保留了源文档的结构和示例
• 代码示例包含语言检测，以提供更好的语法高亮
• 快速参考模式摘自文档中的真实用例
• 所有示例均经过测试，可用于生产环境

更新

如需使用更新后的文档刷新此技能：

1. 使用相同的配置重新运行抓取程序
2. 此技能将使用 docs.agno.com 中的最新信息重新构建