智能体创建与部署指南

从零开始在 PaaS 平台上创建、部署、运行你的 AI 智能体

一、前置条件

# PaaS 服务已在运行 (端口 8000)
curl http://localhost:8000/health
# {"status":"ok","version":"0.1.0"}

# 已有 API Key（如果没有，先创建租户）
python -m agentpaas create-tenant --name "我的空间"
# 输出 API Key，自动保存到 ~/.agentpaas/config.json

二、创建智能体 — 3 种方式

方式 1：快速创建（一行命令）

不写 YAML，直接指定 prompt：

python -m agentpaas agent create \
  --name "代码助手" \
  --prompt "你是一个 Python 代码助手，帮助用户编写、调试和优化代码。用中文回复。" \
  --description "Python 编程辅助" \
  --tags "coding,python"

输出：

Agent created: ag_xxxx
Version: 1
Endpoint: /api/v1/agents/ag_xxxx

方式 2：YAML 配置创建（推荐）

创建配置文件 my-agent.yml：

agentId: my-assistant
name: 我的助手
description: 一个能操控电脑的个人 AI 助手

type: react

model:
  provider: anthropic
  name: claude-sonnet-4-20250514
  temperature: 0.3
  maxTokens: 4096

systemPrompt: |
  你是一个智能助手，能帮用户完成各种任务。
  通过输出 JSON 代码块调用工具：
  ```json
  {"action": "工具名", "input": {参数}}

可用工具: ReadFile, EditFile, WriteFile, Bash, WebSearch, 等42个工具。任务完成时调用: {"action": "terminate", "input": {"answer": "完成摘要"}} 用中文回复，简洁自然。

react: maxSteps: 15 toolTimeout: 30

memory: enabled: true strategy: local size: 30

mcp: localTools:

- ReadFile
- EditFile
- WriteFile
- ListFiles
- SearchContent
- Bash
- GitStatus
- GitDiff
- GitLog
- GitCommit
- CodeSearch
- ProjectMap
- RunTests
- WebSearch
- WebFetch
- TaskCreate
- TaskList
- NotebookEdit
- MemoryStore
- MemoryRecall
- Notify
- terminate

policy:

mode: auto

guard: dangerousCommandBlock: true highRiskConfirmation: true maxOutputLength: 5000


部署：

```bash
python -m agentpaas agent create --name "我的助手" --config my-agent.yml

方式 3：从模板创建

已有的模板：

模板	说明	路径
agent67	全能助手 + 编程 (42 工具)	`agentexample/agent67/agent-config.yml`
research67	科研助手 (论文/实验)	`agentexample/research67/orchestrator.yml`
agentbuilder67	Agent 构建器	`agentexample/agentbuilder67/orchestrator.yml`

复制模板后修改：

cp agentexample/agent67/agent-config.yml my-agent.yml
# 编辑 my-agent.yml 修改 name、systemPrompt 等
python -m agentpaas agent create --name "我的助手" --config my-agent.yml

三、运行智能体

通过 CLI 运行

# 单次执行
python -m agentpaas run ag_xxxx "帮我分析一下当前目录的项目结构"

# 从文件读取输入
python -m agentpaas run ag_xxxx --input-file task.txt

# 覆盖参数
python -m agentpaas run ag_xxxx "写一首诗" --temperature 0.8 --max-steps 5

通过 API 运行

curl -X POST http://localhost:8000/api/v1/agents/ag_xxxx/run \
  -H "Authorization: Bearer ap_your_key" \
  -H "Content-Type: application/json" \
  -d '{"input": "你好，介绍一下你自己"}'

交互式运行（agent67 专用）

python -m agentexample.agent67.run

四、管理智能体

查看列表

python -m agentpaas agent list

查看详情

python -m agentpaas agent get ag_xxxx

更新配置

# 修改 YAML 后重新部署（自动版本递增）
python -m agentpaas agent update ag_xxxx --config my-agent-v2.yml --changelog "优化 prompt"

回滚版本

python -m agentpaas agent rollback ag_xxxx --version 1

查看版本历史

python -m agentpaas agent versions ag_xxxx

删除

python -m agentpaas agent delete ag_xxxx

五、监控

# 平台总览
python -m agentpaas status

# 所有 Agent 健康度
python -m agentpaas status agents

# 单个 Agent 健康度
python -m agentpaas health ag_xxxx

# 运行历史
python -m agentpaas runs ag_xxxx --limit 10

# 运行详情
python -m agentpaas trace run_xxxx

# 用量统计
python -m agentpaas usage --group-by agent

六、42 个可用工具速查

在 YAML 的 mcp.localTools 中声明需要的工具：

文件操作

工具	功能
`ReadFile`	读取文件（文本/PDF/CSV/Notebook/图片）
`EditFile`	精确字符串替换
`WriteFile`	创建/覆盖文件
`ListFiles`	Glob 文件搜索
`SearchContent`	正则内容搜索

代码

工具	功能
`CodeSearch`	语义代码搜索（6 种语言）
`ProjectMap`	项目结构概览
`RunTests`	自动检测框架运行测试

Shell & Git

工具	功能
`Bash`	终端命令（持久 CWD）
`GitStatus` / `GitDiff` / `GitLog` / `GitCommit` / `GitBranch`	Git 全流程

Web

工具	功能
`WebSearch`	网络搜索
`WebFetch`	获取网页→Markdown

Notebook & 文档

工具	功能
`NotebookEdit`	Jupyter Notebook cell 编辑
`DocGen`	Markdown→HTML/PDF/Word
`ChunkSplit`	长文档分块
`OCR`	图片/扫描件文字提取

知识库

工具	功能
`KBCreate` / `KBAdd` / `KBSearch` / `KBList`	知识库管理全流程

任务管理

工具	功能
`TaskCreate` / `TaskUpdate` / `TaskList`	任务创建/更新/列表

记忆 & 学习

工具	功能
`MemoryStore` / `MemoryRecall` / `MemoryList` / `MemoryForget`	持久化记忆
`ScheduleCreate` / `ScheduleList` / `ScheduleDelete`	定时任务
`Notify`	多渠道通知
`EventSubscribe` / `EventList`	事件订阅
`ProfileGet` / `ProfileUpdate`	用户画像
`LearningFeedback` / `LearningStrategies`	自适应学习

七、YAML 配置详解

最小配置

type: simple
systemPrompt: "你是一个助手。"
model:
  name: claude-sonnet-4-20250514

完整配置字段

agentId: string           # Agent 唯一标识
name: string              # 显示名称
description: string       # 描述
type: simple|react|chain|router|parallel  # 类型

model:
  provider: anthropic|openai|dashscope    # LLM 提供商
  name: string            # 模型名
  temperature: 0.0-1.0    # 温度
  maxTokens: int          # 最大输出 token
  fallback: [string]      # 备选模型列表

systemPrompt: string      # 系统提示词

react:                    # ReAct 模式配置
  maxSteps: int           # 最大步数 (建议 10-20)
  toolTimeout: int        # 工具超时秒数
  thinkTimeout: int       # LLM 思考超时

memory:
  enabled: bool           # 启用记忆
  strategy: local|redis   # 存储策略
  size: int               # 记忆条数上限
  ttl: int                # 记忆存活秒数

mcp:
  localTools: [string]    # 启用的工具列表
  policy:
    mode: auto|force|disable  # 工具策略

runtime:
  engine: recursive|cek|adaptive # 执行引擎选择（默认 recursive）
                                 # cek: 逐步成本监控、暂停/恢复、循环检测
                                 # adaptive: 自动选择

guard:
  dangerousCommandBlock: bool    # 拦截危险命令
  highRiskConfirmation: bool     # 高风险操作确认
  maxOutputLength: int           # 输出长度限制
  validator: string              # 输出验证表达式
  retry: int                     # 验证失败重试次数
  fallback: error|empty|last     # 失败后策略

hooks:                    # Hook 配置
  pre_tool:
    - command: string     # Shell hook
  post_llm:
    - command: string

persona:                  # 人格配置
  name: string            # lambda🐑 / jarvis / friday / 自定义
  style: casual|formal|efficient
  template: string        # 内置模板名

八、典型场景

编程助手

type: react
systemPrompt: "你是编程助手。编程流程: ReadFile→CodeSearch→EditFile→RunTests→GitCommit"
mcp:
  localTools: [ReadFile, EditFile, WriteFile, CodeSearch, ProjectMap, RunTests, Bash, GitStatus, GitDiff, GitCommit, terminate]

知识问答助手

type: react
systemPrompt: "你是知识问答助手。先在知识库中搜索，搜不到再用 WebSearch。"
mcp:
  localTools: [KBSearch, KBAdd, WebSearch, WebFetch, WriteFile, terminate]

文件管理助手

type: react
systemPrompt: "你是文件管理助手。帮用户整理、搜索、分类文件。"
mcp:
  localTools: [ReadFile, WriteFile, ListFiles, SearchContent, Bash, Notify, terminate]

日报生成助手

type: react
systemPrompt: "你是日报生成助手。每天分析 git log 和文件变更，生成日报保存到桌面。"
mcp:
  localTools: [GitLog, GitDiff, ProjectMap, WriteFile, DocGen, Notify, terminate]

九、常见问题

Q: Agent 超时？ 增大 react.thinkTimeout 和 react.toolTimeout，或换更快的模型。

Q: 工具调用失败？ 检查 mcp.localTools 中是否声明了该工具。42 个工具名区分大小写。

Q: 如何查看所有可用工具？

python -c "from lambdagent.builtin_tools.registry import BUILTIN_TOOLS; print(sorted(BUILTIN_TOOLS.keys()))"

Q: 如何让 Agent 记住我？ 在 mcp.localTools 中加入 MemoryStore 和 MemoryRecall。

Q: 如何本地交互式运行？

python -m agentexample.agent67.run

Q: 如何微信绑定？

python -m agentpaas wechat ag_xxxx

AGENT_GUIDE.md 9.7 KB Permanentný odkaz História Raw