Phidata Agent 框架¶

为什么要学¶

Phidata 是一个生产级 AI Agent 框架，设计理念是让构建有记忆、有知识、能使用工具的 Agent 变得简单：

开箱即用：内置工具、知识库、记忆系统，几行代码创建 Agent
生产就绪：内置监控、日志、API 端点
团队协作：支持多 Agent 协作（Agent Teams）
知识驱动：RAG 作为一等公民，内置向量数据库集成
全模型支持：OpenAI/Anthropic/Ollama/Groq 等

如果你想快速构建能上生产的 AI Agent，Phidata 是最务实的选择之一。

核心概念¶

白话解释¶

Phidata 把 Agent 设计成一个有三大能力的实体： - Tools（工具）：Agent 能做什么（搜索、写文件、调 API） - Knowledge（知识）：Agent 知道什么（RAG 知识库） - Memory（记忆）：Agent 记得什么（对话历史和长期记忆）

核心概念对照表¶

概念	说明	类比
Agent	有工具/知识/记忆的AI	一个有能力的员工
Tool	Agent可调用的函数	员工的工作工具
Knowledge	RAG知识库	员工的参考资料
Memory	对话/长期记忆	员工的笔记本
Storage	持久化存储后端	数据库
Team	多Agent协作组	工作小组
Playground	内置测试UI	开发者调试工具
Monitoring	运行监控	管理仪表盘

安装配置¶

安装¶

pip install phidata

# 带常用依赖
pip install phidata openai pgvector sqlalchemy

# 或使用特定组件
pip install phidata[aws]     # AWS集成
pip install phidata[docker]  # Docker工具

环境配置¶

export OPENAI_API_KEY="sk-..."
# 或
export ANTHROPIC_API_KEY="sk-ant-..."

# 可选: Phidata Cloud监控
export PHI_API_KEY="phi-..."

快速上手¶

最简Agent¶

from phi.agent import Agent
from phi.model.openai import OpenAIChat

agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    description="你是一个有帮助的AI助手",
    markdown=True
)

agent.print_response("用Python写一个快速排序算法")

带工具的Agent¶

from phi.agent import Agent
from phi.model.openai import OpenAIChat
from phi.tools.duckduckgo import DuckDuckGo
from phi.tools.newspaper4k import Newspaper4k

# 网络搜索+文章阅读Agent
researcher = Agent(
    name="Researcher",
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[DuckDuckGo(), Newspaper4k()],
    description="你是一个研究助手，能搜索网络并阅读文章",
    instructions=[
        "搜索最新信息",
        "阅读相关文章获取详情",
        "用中文总结发现"
    ],
    show_tool_calls=True,
    markdown=True
)

researcher.print_response("2024年AI Agent领域有哪些重要进展?")

带知识库的Agent¶

from phi.agent import Agent
from phi.model.openai import OpenAIChat
from phi.knowledge.pdf import PDFKnowledgeBase
from phi.vectordb.pgvector import PgVector

# 创建知识库(基于PDF文档)
knowledge = PDFKnowledgeBase(
    path="./docs/",  # PDF文件目录
    vector_db=PgVector(
        table_name="pdf_documents",
        db_url="postgresql://localhost:5432/aidb"
    )
)

# 加载文档到向量库
knowledge.load()

# 创建RAG Agent
doc_agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    knowledge=knowledge,
    search_knowledge=True,
    description="你是一个文档问答助手，基于给定文档回答问题",
    instructions=["始终引用文档来源", "如果文档中没有答案，明确说明"]
)

doc_agent.print_response("这份文档的主要结论是什么?")

进阶用法¶

1. Agent Team（多Agent协作）¶

from phi.agent import Agent
from phi.model.openai import OpenAIChat
from phi.tools.duckduckgo import DuckDuckGo
from phi.tools.yfinance import YFinanceTools

# 网络研究员
web_researcher = Agent(
    name="Web Researcher",
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[DuckDuckGo()],
    role="搜索网络获取最新信息",
    instructions=["搜索相关信息", "提供来源链接"]
)

# 财务分析师
financial_analyst = Agent(
    name="Financial Analyst",
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[YFinanceTools(stock_price=True, analyst_recommendations=True)],
    role="分析财务数据和股票信息",
    instructions=["提供数据支持的分析", "注明数据来源"]
)

# 团队协调者
team_leader = Agent(
    name="Team Leader",
    model=OpenAIChat(id="gpt-4o"),
    team=[web_researcher, financial_analyst],
    instructions=[
        "协调团队成员完成任务",
        "综合各成员的发现",
        "给出最终建议"
    ],
    markdown=True
)

team_leader.print_response("分析一下NVIDIA目前的投资价值")

2. 内置记忆系统¶

from phi.agent import Agent
from phi.model.openai import OpenAIChat
from phi.memory.db.postgres import PgMemory
from phi.storage.agent.postgres import PgAgentStorage

# Agent带持久化记忆
agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    # 会话存储
    storage=PgAgentStorage(
        table_name="agent_sessions",
        db_url="postgresql://localhost:5432/aidb"
    ),
    # 长期记忆
    memory=PgMemory(
        table_name="agent_memory",
        db_url="postgresql://localhost:5432/aidb"
    ),
    # 启用记忆功能
    add_history_to_messages=True,
    num_history_responses=5,
    create_user_memories=True,   # 自动提取用户偏好
    create_session_summary=True, # 自动生成对话摘要
)

# 第一次对话
agent.print_response("我叫张三，我是Python开发者", session_id="s1")

# 后续对话（Agent会记住）
agent.print_response("根据我的背景，推荐一些学习资源", session_id="s1")

3. 自定义工具¶

from phi.agent import Agent
from phi.tools import Toolkit
import httpx

class WeatherTool(Toolkit):
    def __init__(self):
        super().__init__(name="weather")
        self.register(self.get_weather)

    def get_weather(self, city: str) -> str:
        """获取指定城市的天气信息

        Args:
            city: 城市名称，如"北京"、"上海"
        """
        # 实际调用天气API
        response = httpx.get(
            f"https://wttr.in/{city}?format=j1"
        )
        data = response.json()
        current = data["current_condition"][0]
        return f"{city}: {current['temp_C']}°C, {current['weatherDesc'][0]['value']}"

# 使用自定义工具
agent = Agent(
    tools=[WeatherTool()],
    show_tool_calls=True
)

agent.print_response("今天北京和上海的天气怎么样?")

4. 结构化输出¶

from phi.agent import Agent
from phi.model.openai import OpenAIChat
from pydantic import BaseModel, Field

class MovieRecommendation(BaseModel):
    title: str = Field(description="电影名称")
    year: int = Field(description="上映年份")
    genre: str = Field(description="类型")
    reason: str = Field(description="推荐理由")
    rating: float = Field(description="评分(1-10)", ge=1, le=10)

agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    response_model=MovieRecommendation  # 结构化输出
)

result = agent.run("推荐一部科幻电影")
print(f"{result.title} ({result.year}) - {result.rating}/10")
print(f"理由: {result.reason}")

5. 多种知识源¶

from phi.knowledge.pdf import PDFKnowledgeBase
from phi.knowledge.text import TextKnowledgeBase
from phi.knowledge.website import WebsiteKnowledgeBase
from phi.knowledge.combined import CombinedKnowledgeBase
from phi.vectordb.pgvector import PgVector

db_url = "postgresql://localhost:5432/aidb"

# 组合多种知识源
knowledge = CombinedKnowledgeBase(
    sources=[
        PDFKnowledgeBase(path="./pdfs/", vector_db=PgVector(table_name="pdfs", db_url=db_url)),
        TextKnowledgeBase(path="./notes/", vector_db=PgVector(table_name="notes", db_url=db_url)),
        WebsiteKnowledgeBase(
            urls=["https://docs.example.com"],
            vector_db=PgVector(table_name="web", db_url=db_url)
        )
    ]
)

knowledge.load()

6. API 部署¶

from phi.agent import Agent
from phi.playground import Playground, serve_playground_app

# 创建Agent
agent = Agent(
    name="Assistant",
    model=OpenAIChat(id="gpt-4o-mini"),
    description="通用AI助手"
)

# 启动Playground(自带Web UI)
app = Playground(agents=[agent]).get_app()

if __name__ == "__main__":
    serve_playground_app("app:app", reload=True)
    # 访问 http://localhost:7777

7. 使用本地模型¶

from phi.agent import Agent
from phi.model.ollama import Ollama

# 使用Ollama本地模型
agent = Agent(
    model=Ollama(id="llama3.2"),
    description="本地AI助手",
    markdown=True
)

agent.print_response("解释Python的GIL")

常见问题¶

Q1: 和 LangChain/CrewAI 的区别？¶

特性	Phidata	LangChain	CrewAI
定位	生产级Agent框架	通用LLM框架	多Agent协作
复杂度	中等	高	低
内置功能	丰富(知识/记忆/监控)	需要组合	聚焦协作
学习曲线	平缓	陡峭	平缓
生产就绪	高	中	中

Q2: 知识库更新后如何刷新？¶

# 重新加载（会增量更新）
knowledge.load(recreate=False)

# 完全重建
knowledge.load(recreate=True)

Q3: 如何调试Agent行为？¶

agent = Agent(
    debug_mode=True,       # 详细日志
    show_tool_calls=True,  # 显示工具调用
    monitoring=True        # 启用监控
)

Q4: 记忆占用太多context怎么办？¶

agent = Agent(
    num_history_responses=3,     # 只保留最近3轮
    create_session_summary=True, # 用摘要替代完整历史
)

参考资源¶

Phidata 官方文档 - 完整文档
Phidata GitHub - 源代码
Cookbook - 实战示例
Phidata Cloud - 监控平台
Agent 模板 - 快速启动模板