docs: Agent creation and deployment guide

Complete guide covering:
- 3 ways to create agents (quick/YAML/template)
- CLI and API execution
- 42 tools reference table
- Full YAML config schema
- 4 scenario templates (coding/knowledge/file/report)
- Monitoring and management commands
- FAQ

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

AGENT_GUIDE.md

@@ -0,0 +1,427 @@
+# 智能体创建与部署指南
+
+> 从零开始在 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  # 工具策略
+
+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
+```