【AskAI系列课程】：P1.接入 Agno 框架 - 避坑指南与国内模型接入

手把手教你正确集成Agno框架到FastAPI项目，避开官方文档的常见陷阱，并演示如何使用OpenAILike接入国内AI模型服务。包含完整的调试流程和最佳实践。

OliverYeung

291人浏览 · 2025-09-15 08:00:00

OliverYeung · 2025-09-15 08:00:00 发布

在上一篇文章中，我们介绍了AskAI系列课程的整体架构和技术选型。今天我们开始动手实践，将Agno框架集成到我们的项目中。在开始之前，让我们先了解一下Agno到底是什么，以及为什么它是构建AI Agent的理想选择。

在这里插入图片描述

什么是Agno？一个让AI Agent开发变简单的框架

Agno简介

Agno是一个专为构建多智能体系统而设计的Python框架。简单来说，它就像是给AI开发者提供的一个"乐高积木套装"，让你可以轻松地：

创建智能Agent：每个Agent都有自己的"专业技能"
组建Agent团队：让多个Agent协作完成复杂任务
管理对话记忆：Agent能记住之前的对话内容
集成外部工具：让Agent能够调用API、搜索网络、读取文档等
构建工作流：定义Agent之间的协作流程

为什么选择Agno？

相比其他AI框架，Agno有几个突出的优势：

⚡️ 性能优异

高性能运行时，专为生产环境优化
支持异步处理，能够处理大量并发请求
内置会话管理和状态持久化

🛠️ 开发友好

API设计简洁直观，学习曲线平缓
丰富的内置工具和集成选项
完善的文档和示例代码

🔧 功能全面

支持多种LLM提供商（OpenAI、Claude、国内模型等）
内置向量数据库集成（PgVector、LanceDB等）
提供Web界面和API接口

🌐 生产就绪

内置安全机制和错误处理
支持Docker部署和云原生架构
提供监控、模拟测试和调试工具

Agno的核心概念

让我们通过一个简单的例子来理解Agno的核心概念：

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.duckduckgo import DuckDuckGoTools

# 创建一个具备搜索能力的研究员Agent
researcher = Agent(
    name="研究员",
    role="专业的信息研究专家",
    model=OpenAIChat("gpt-4o"),
    tools=[DuckDuckGoTools()],  # 给Agent配备搜索工具
    instructions=["总是提供准确的信息来源"]
)

# Agent可以自主决定何时使用工具
response = researcher.run("最新的AI发展趋势是什么？")

在这个例子中：

Agent：就像一个有专业技能的虚拟员工
Model：Agent的"大脑"，负责理解和生成文本
Tools：Agent可以使用的"工具箱"
Instructions：给Agent的工作指导原则

当用户提问时，Agent 会使用 Model 根据 Instructions 分析该调用什么 Tools 来收集必要信息、进行必要操作，最终生成回答。

完整的项目结构

我们在博客网站目录下创建一个 ask-ai-server 目录，用于集成 Agno 框架，存放所有与AskAI相关的服务端代码。让我们看看完整的项目结构和代码实现：

ask-ai-server/
├── .env                 # 环境变量配置
├── fastcar_os.py       # 主应用文件
├── requirements.txt    # Python依赖
└── README.md          # 项目说明

完整的应用代码

import os
from dotenv import load_dotenv
from agno.agent import Agent
from agno.models.openai.like import OpenAILike
from agno.os import AgentOS
from agno.db.postgres import PostgresDb
from starlette.middleware.cors import CORSMiddleware

# 加载环境变量
load_dotenv()

# 设置数据库
db = PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

# 创建AI助手
assistant = Agent(
    name="Assistant",
    model=OpenAILike(
        id=os.getenv("ARK_BIG_THINKING_MODEL"),
        api_key=os.getenv("ARK_API_KEY"),
        base_url=os.getenv("ARK_BASE_URL"),
    ),
    instructions=["你是我个人网站的AI助手，请根据用户的问题给出回答。"],
    markdown=True,
    db=db,
)

# 创建AgentOS
agent_os = AgentOS(
    os_id="fastcar-os",
    description="FastCar AI Assistant",
    agents=[assistant],
)

# 获取FastAPI应用实例
app = agent_os.get_app()

# 添加CORS中间件
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://fastcar.fun","https://os.agno.com", "http://localhost"],
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE"],
    allow_headers=["*"],
)

# 添加自定义路由
@app.get("/hello")
async def hello():
    return {"message": "Hello, World!"}

if __name__ == "__main__":
    # 启动服务，默认端口7777
    agent_os.serve(app="fastcar_os:app", reload=True)

关键配置说明

数据库配置：使用PostgreSQL存储Agent的对话历史和状态
CORS配置：允许来自指定域名的跨域请求，特别注意添加了https://os.agno.com
模型配置：使用OpenAILike接入国内AI服务
Agent配置：设置中文指令和Markdown输出支持

接入国内AI模型：OpenAILike的正确使用

支持国内符合 OpenAI API 规范的 LLM 服务。常见如下：

DeepSeek：DeepSeek 大模型
字节跳动豆包：通过火山引擎提供API服务
阿里云百炼：提供多种大模型API
智谱AI：GLM系列模型
月之暗面Kimi：长文本处理能力强
百度千帆：文心一言等模型
腾讯混元：腾讯自研大模型

配置示例：接入字节跳动豆包

以字节跳动的豆包（通过火山引擎ARK平台）为例：

from agno.models.openai.like import OpenAILike
import os

# 配置环境变量
# ARK_API_KEY=你的API密钥
# ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
# ARK_BIG_THINKING_MODEL=doubao-seed-1-6-thinking-250715

model = OpenAILike(
    id=os.getenv("ARK_BIG_THINKING_MODEL"),  # 模型端点ID
    api_key=os.getenv("ARK_API_KEY"),        # API密钥
    base_url=os.getenv("ARK_BASE_URL"),      # API基础URL
)

官方文档的陷阱：FastAPI应用初始化问题

在实际项目中，我们往往需要添加一些自定义的API接口，比如数据统计接口、用户管理接口等。这时候就会遇到一个重要问题：如何正确地在Agno应用中添加自定义路由？

按照Agno官方文档的某些示例，你可能会看到这样的代码：

# ❌ 错误的做法 - 目前官方文档示例有问题
from fastapi import FastAPI
from agno.agent import Agent
from agno.models.openai import OpenAIChat

app = FastAPI()  # 这里会导致与AgnoOS冲突！

# 添加自定义路由
@app.get("/status")
async def status_check():
    return {"status": "healthy"}

# 将 app 传给 AgentOS
agent_os = AgentOS(
    agents=[Agent(id="basic-agent", model=OpenAIChat(id="gpt-5-mini"))],
    fastapi_app=app  # Your custom FastAPI app
)

# Get the combined app with both AgentOS and your routes
app = agent_os.get_app()

问题分析

这种写法的问题在于：

路由冲突：直接创建FastAPI()实例会与AgentOS的内置路由产生冲突
架构不一致：违背了AgentOS的设计理念，无法享受框架的完整生态

正确的解决方案

正确的做法是使用AgentOS来管理整个应用，然后通过agent_os.get_app()获取FastAPI实例：

# ✅ 正确的做法
from agno.os import AgentOS
from agno.agent import Agent
from agno.models.openai.like import OpenAILike

# 创建Agent
assistant = Agent(
    name="Assistant",
    model=OpenAILike(
        id=os.getenv("ARK_BIG_THINKING_MODEL"),
        api_key=os.getenv("ARK_API_KEY"),
        base_url=os.getenv("ARK_BASE_URL"),
    ),
    instructions=["你是我个人网站的AI助手，请根据用户的问题给出回答。"],
    markdown=True,
)

# 创建AgentOS实例
agent_os = AgentOS(
    os_id="fastcar-os",
    description="FastCar AI Assistant",
    agents=[assistant],
)

# ✅ 正确的做法：通过AgentOS获取FastAPI应用
app = agent_os.get_app()

# 现在可以安全地添加自定义路由
@app.get("/hello")
async def hello():
    return {"message": "Hello, World!"}

@app.get("/stats")
async def get_stats():
    return {"total_users": 1000, "active_sessions": 50}

为什么这样做是正确的？

完整的AgnoOS功能：通过AgentOS创建的应用自动包含了所有内置功能
路由管理：AgentOS会自动管理Agent相关的路由，避免冲突
扩展性：可以轻松添加更多Agent、Team或Workflow
标准化：符合Agno框架的最佳实践

接入os.agno.com进行在线调试

Agno框架提供了一个非常棒的在线调试平台：os.agno.com。在我们准备好前端 UI 前可以重点通过这个平台调试好 Agent 的功能，通过这个平台，你可以：

实时测试你的Agent
查看对话历史和Agent状态
调试Agent的推理过程
监控API调用情况

配置步骤

确保CORS配置正确

在你的应用中添加https://os.agno.com到允许的源：

app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "https://fastcar.fun",
        "https://os.agno.com",  # 重要：允许Agno调试平台访问
        "http://localhost"
    ],
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE"],
    allow_headers=["*"],
)