Pi Agent: 第一次对话
最后更新：2026-08-31
Hello World 永远是学习新工具的第一步。这一课让 Pi Agent 真正"开口说话"。
1. CLI 快速对话
安装完成后，最简单的方式是命令行直接对话：
BASH
pi-agent chat "你好，请介绍一下你自己"
输出：
TEXT
📖 仅展示
🤖 Pi Agent v0.8.0
📡 Provider: deepseek (deepseek-chat)
你好！我是 Pi Agent，一个轻量级 AI 智能体框架。我可以帮你回答问题、
调用工具、执行任务。和我聊天就像和一个能动手的 AI 伙伴对话！
(1) 指定提供商
BASH
pi-agent chat --provider openai --model gpt-4o "解释量子纠缠"
(2) 指定技能
BASH
pi-agent chat --skill code_review "审查这段 Python 代码"
2. Python 代码对话
更灵活的方式是用 Python API：
(1) 最简对话
PYTHON
from pi_agent import Agent
agent = Agent(name="hello")
response = agent.chat("你好，Pi Agent！")
print(response)
(2) 多轮对话
PYTHON
from pi_agent import Agent
agent = Agent(name="tutor", system_prompt="你是一个 Python 编程导师")
# 第一轮
r1 = agent.chat("什么是列表推导式？")
print(r1)
# 第二轮——Agent 记得之前的上下文
r2 = agent.chat("给我一个实际例子")
print(r2)
# 第三轮
r3 = agent.chat("和 for 循环相比有什么优势？")
print(r3)
(3) 获取结构化响应
PYTHON
from pi_agent import Agent
agent = Agent(name="structured")
response = agent.chat(
"列出 5 种编程语言的名称和发明年份",
response_format="json"
)
print(type(response)) # <class 'dict'>
print(response)
# {"languages": [{"name": "Python", "year": 1991}, ...]}
3. 消息格式
Pi Agent 内部使用标准消息格式：
PYTHON
messages = [
{"role": "system", "content": "你是一个编程助手"},
{"role": "user", "content": "什么是装饰器？"},
{"role": "assistant", "content": "装饰器是..."},
{"role": "user", "content": "能给个例子吗？"}
]
| 角色 | 说明 |
|---|---|
| system | 系统提示，定义 Agent 行为 |
| user | 用户输入 |
| assistant | Agent 回复 |
| tool | 工具调用结果 |
4. 系统提示词
系统提示词定义 Agent 的"人格"和行为边界：
▶ 示例 1：不同角色的 Agent（难度⭐）
PYTHON
from pi_agent import Agent
coder = Agent(
name="coder",
system_prompt="你是一个 Python 专家，回答简洁，只给代码和关键解释"
)
teacher = Agent(
name="teacher",
system_prompt="你是一个耐心的编程老师，用比喻和步骤详细解释概念"
)
q = "什么是生成器？"
print("=== Coder ===")
print(coder.chat(q))
# 生成器是使用 yield 的函数，惰性求值...
print("=== Teacher ===")
print(teacher.chat(q))
# 想象你在看电影，不是一次下载整部电影...
5. 流式输出
长回复时，流式输出可以实时看到结果：
PYTHON
from pi_agent import Agent
agent = Agent(name="stream")
for chunk in agent.chat_stream("写一首关于编程的诗"):
print(chunk, end="", flush=True)
Alice 对比了普通模式和流式模式："流式输出的体验好太多了，不用盯着空白屏幕等半天。"
Bob 补充："技术博客写作、代码生成这些长文本场景，流式输出几乎是必需的。"
6. 响应对象详解
chat() 方法返回的不仅是文本，还包含元数据：
PYTHON
from pi_agent import Agent
agent = Agent(name="meta")
response = agent.chat("1+1=?")
print(response.text) # "2"
print(response.model) # "deepseek-chat"
print(response.usage) # {"prompt_tokens": 12, "completion_tokens": 3}
print(response.tool_calls) # [] (如果调用了工具，这里会有记录)
print(response.finish_reason) # "stop"
❓ 常见问题
Q chat() 和 chat_stream() 该用哪个？
A 短问答用 chat()，长文本生成用 chat_stream()。流式输出不影响最终结果，只影响用户体验。
Q 多轮对话的上下文会无限增长吗？
A 不会。Pi Agent 自动管理上下文窗口，超出限制时会截断最早的消息。你可以在创建 Agent 时设置 context_window 参数。
Q 如何在对话中强制 Agent 使用工具？
A 设置 tool_choice="required"，或在消息中明确指示"请使用 search 工具查找..."。
📖 小节
- CLI 用
pi-agent chat快速对话，Python 用Agent.chat()编程调用 - 支持多轮对话、结构化响应、流式输出
- 系统提示词定义 Agent 角色，消息格式遵循 role/content 标准
- 响应对象包含文本、模型信息、token 用量等元数据
📝 作业
- 基础题（难度⭐）：用 CLI 和 Python 两种方式各发送一条消息，对比体验。
- 进阶题（难度⭐⭐）：创建两个不同 system_prompt 的 Agent，对同一问题给出不同风格的回答。
- 挑战题（难度⭐⭐⭐）：用流式输出实现一个"实时打字机"效果，逐字显示 Agent 的回复。
