# 智能体创建与部署指南

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

---

## 一、前置条件

```bash
# 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：

```bash
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`：

```yaml
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` |

复制模板后修改：

```bash
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 运行

```bash
# 单次执行
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 运行

```bash
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 专用）

```bash
python -m agentexample.agent67.run
```

---

## 四、管理智能体

### 查看列表

```bash
python -m agentpaas agent list
```

### 查看详情

```bash
python -m agentpaas agent get ag_xxxx
```

### 更新配置

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

### 回滚版本

```bash
python -m agentpaas agent rollback ag_xxxx --version 1
```

### 查看版本历史

```bash
python -m agentpaas agent versions ag_xxxx
```

### 删除

```bash
python -m agentpaas agent delete ag_xxxx
```

---

## 五、监控

```bash
# 平台总览
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 配置详解

### 最小配置

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

### 完整配置字段

```yaml
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        # 内置模板名
```

---

## 八、典型场景

### 编程助手

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

### 知识问答助手

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

### 文件管理助手

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

### 日报生成助手

```yaml
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: 如何查看所有可用工具？**
```bash
python -c "from lambdagent.builtin_tools.registry import BUILTIN_TOOLS; print(sorted(BUILTIN_TOOLS.keys()))"
```

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

**Q: 如何本地交互式运行？**
```bash
python -m agentexample.agent67.run
```

**Q: 如何微信绑定？**
```bash
python -m agentpaas wechat ag_xxxx
```