# lambdagentpaas CLI 完整使用说明

本文档涵盖两个 CLI 工具：

- **`lambdagent`** — Lambda 演算 Agent DSL 的命令行入口（编译/执行/调试）
- **`agentpaas`** — Agent Platform as a Service 平台管理（服务/部署/监控）

---

# Part I — lambdagent CLI

> Unix 管道 `|` = 函数组合 `>>`，每条命令 = 一次或多次 β-规约。

## 目录（lambdagent）

- [安装与配置](#安装与配置)
- [命令总览](#命令总览)
- [compile — 编译 YAML → Lambda 项](#compile--编译-yaml--lambda-项)
- [run — 编译 + 执行 Agent](#run--编译--执行-agent)
- [repl — 交互式会话](#repl--交互式会话)
- [lint — 静态分析](#lint--静态分析)
- [trace — 查看 β-规约追踪](#trace--查看-β-规约追踪)
- [lambda — 导出 Lambda 表达式](#lambda--导出-lambda-表达式)
- [tools — 列出和测试工具](#tools--列出和测试工具)
- [version — 版本信息](#version--版本信息)
- [高级用法](#高级用法)
- [YAML 配置参考](#yaml-配置参考)
- [退出码](#退出码)

---

## 安装与配置

```bash
# 安装依赖
pip install pyyaml anthropic
# 可选：pip install openai redis cryptography

# 设置 API Key（至少选一个 — claude-code provider 不需要 API Key）
export ANTHROPIC_API_KEY="sk-ant-..."
# 或
export OPENAI_API_KEY="sk-..."
# 或（阿里云 DashScope）
export DASHSCOPE_API_KEY="sk-..."
# 或（无 Key，使用 Claude Code Max Plan）
# provider: claude-code 无需 API Key，直接调用 Claude Code CLI
```

验证安装：

```bash
python -m lambdagent version
# lambdagent v2.0.0
# Lambda Calculus Agent DSL
# 11 core constructs — strict lambda correspondence
```

---

## 命令总览

```
python -m lambdagent <command> [options]

Commands:
  compile   编译 YAML → Lambda 项（不执行）
  run       编译 + 执行 Agent
  repl      交互式 REPL（持久会话）
  lint      静态分析 Agent 配置
  trace     查看/回放 β-规约追踪
  lambda    导出纯 Lambda 表达式
  tools     列出和测试 MCP/本地工具
  version   版本信息
```

---

## compile — 编译 YAML → Lambda 项

将 YAML 配置编译为 Lambda 项结构，不实际执行。用于验证配置正确性。

```bash
python -m lambdagent compile <config.yml> [--format text|json] [--validate]
```

### 参数

| 参数 | 说明 |
|------|------|
| `config` | YAML 配置文件路径 |
| `--format text\|json` | 输出格式（默认 `text`） |
| `--validate` | 同时运行 lint 检查 |

### 示例

```bash
# 查看编译结构
python -m lambdagent compile agent-config.yml

# JSON 格式输出
python -m lambdagent compile agent-config.yml --format json

# 编译 + lint
python -m lambdagent compile agent-config.yml --validate
```

输出示例：
```
agent-config =
  # type: react (Y combinator + tool routing)
  Y_10(λself. λstate.
    let t = think(state) in
    CASE (classify t) [
      ("search", λx. MCP("mcp-server", "search", x))
      ("terminate", λx. x)    ← base case
    ] >> λobs.
    IF (obs = t) THEN t ELSE self(state ⊕ format(t, obs))
  )
```

---

## run — 编译 + 执行 Agent

编译 YAML 配置并执行 Agent，输出最终结果。

```bash
python -m lambdagent run <config.yml> [input] [options]
```

### 参数

| 参数 | 说明 |
|------|------|
| `config` | YAML 配置文件路径 |
| `input` | 输入文本。使用 `-` 从 stdin 读取 |
| `--input-file FILE` | 从文件读取输入 |
| `--model MODEL` | 覆盖模型（如 `claude-sonnet-4-20250514`） |
| `--temperature FLOAT` | 覆盖温度 |
| `--max-steps INT` | 覆盖最大步数（ReAct 模式） |
| `--tool NAME=CMD` | 注入 CLI 工具（可重复使用） |
| `--engine recursive\|cek\|adaptive` | 选择执行引擎（默认 recursive） |
| `--timeout INT` | 总超时秒数（默认 300） |
| `--trace` | 打印 β-规约追踪 |
| `--trace-file FILE` | 保存追踪到 JSON 文件 |
| `--format text\|json` | 输出格式 |
| `--verbose` | 打印所有中间步骤 |
| `--quiet` | 只输出最终结果 |

### 基本用法

```bash
# 直接输入
python -m lambdagent run agent-config.yml "帮我写一个快速排序"

# 从 stdin 读取输入
echo "分析这段日志" | python -m lambdagent run agent-config.yml -

# 从文件读取输入
python -m lambdagent run agent-config.yml --input-file question.txt
```

### run.py --claude (agent67)

`agentexample/agent67/run.py` 是个人助理的入口，支持 `--claude` 标志强制使用 Claude Code 后端：

```bash
# 默认：自动检测后端（Ollama → Claude Code → API）
python run.py

# 强制使用 Claude Code Max Plan（跳过 Ollama 检测，无需 API Key）
python run.py --claude

# 强制 Claude Code + 指定模型
python run.py --claude --model opus

# 使用 Ollama 本地模型
python run.py --ollama

# 使用 API Key 模式
python run.py --api
```

`--claude` 的效果：设置 backend 为 `BACKEND_CLAUDE_CODE`，默认模型 `sonnet`，不需要任何 API Key 环境变量。

### 覆盖模型参数

```bash
# 使用 GPT-4o 替代默认模型
python -m lambdagent run agent-config.yml "Hello" --model gpt-4o

# 使用高温度（更有创意）
python -m lambdagent run agent-config.yml "写一首诗" --temperature 0.8

# 限制 ReAct 步数
python -m lambdagent run agent-config.yml "搜索资料" --max-steps 5
```

### 注入 CLI 工具

`--tool` 参数将 shell 命令包装为 Agent 可用的工具（Lambda 语义: `λx. exec(cmd, x)`）：

```bash
# 注入静态命令工具
python -m lambdagent run agent-config.yml "分析日志" \
  --tool grep="grep -c ERROR /var/log/app.log"

# 注入参数化工具（{} 被 Agent 输出替换）
python -m lambdagent run agent-config.yml "搜索代码" \
  --tool search="grep -r {} src/"

# 注入多个工具
python -m lambdagent run agent-config.yml "分析项目" \
  --tool loc="find . -name '*.py' | wc -l" \
  --tool deps="pip list --format=json"
```

> **安全说明**：`--tool` 会自动拦截危险命令（`rm -rf /`、`fork bomb` 等），参数化模式下输入会经过 `shlex.quote` 转义。

### 追踪与调试

```bash
# 打印 β-规约追踪
python -m lambdagent run agent-config.yml "1+1" --trace

# 保存追踪到文件（后续用 trace 命令分析）
python -m lambdagent run agent-config.yml "task" --trace-file trace.json

# JSON 输出（含 result + trace + stats）
python -m lambdagent run agent-config.yml "task" --format json

# 详细模式（打印每步中间结果）
python -m lambdagent run agent-config.yml "task" --verbose
```

### Unix 管道组合

```bash
# 管道输入
cat article.txt | python -m lambdagent run summarizer.yml -

# 链式处理（CLI 层面的函数组合）
cat data.csv | \
  python -m lambdagent run extract.yml - | \
  python -m lambdagent run analyze.yml - | \
  python -m lambdagent run report.yml -

# 与其他命令组合
python -m lambdagent run agent-config.yml "list files" --quiet | xargs wc -l
```

---

## repl — 交互式会话

启动持久化 REPL 会话，支持多轮对话和内置命令。

```bash
python -m lambdagent repl <config.yml> [--model MODEL] [--temperature FLOAT] [--tool NAME=CMD]
```

### 进入 REPL

```bash
python -m lambdagent repl agent-config.yml
```

输出：
```
lambdagent REPL v2.0
Agent: my-agent (react, maxSteps=10)
Lambda: Y_10(λself.λstate. think(state) >> route >> observe)
Type :help for commands, :quit to exit

λ>
```

### REPL 内置命令

| 命令 | 说明 |
|------|------|
| `:help` | 显示帮助 |
| `:quit` / `:q` / `:exit` | 退出 REPL |
| `:trace` | 显示上次执行的 β-规约追踪 |
| `:trace N` | 显示第 N 步的详细信息 |
| `:memory` | 显示 Memory 内容 |
| `:memory clear` | 清空 Memory |
| `:lambda` | 显示 Agent 的 Lambda 表达式 |
| `:lint` | 对当前配置运行 lint |
| `:reload` | 重新加载 YAML 配置（热更新） |
| `:stats` | 显示会话统计 |
| `:tools` | 列出可用工具 |

### REPL 会话示例

```
λ> 帮我写一个冒泡排序
  [β[0] think 2.3s] 我需要写一个冒泡排序...
  [β[1] Tool:terminate 0.0s] 返回结果

def bubble_sort(arr):
    n = len(arr)
    for i in range(n):
        for j in range(0, n-i-1):
            if arr[j] > arr[j+1]:
                arr[j], arr[j+1] = arr[j+1], arr[j]
    return arr
(2 β-reductions, 2.3s)

λ> :trace 0
  β[0] think
    Duration: 2312ms
    Model: claude-sonnet-4-20250514
    Input:  帮我写一个冒泡排序...
    Output: 我需要写一个冒泡排序...

λ> :stats
  Session: 45s
  Total β-reductions: 2
  Trace entries: 2

λ> :quit
Session: 2 β-reductions in 45s
```

---

## lint — 静态分析

对 Agent 配置进行静态分析，检查 26+ 条规则（含 3 条安全规则 S001-S003）。

```bash
python -m lambdagent lint <config.yml|directory> [--level error|warn|info] [--format text|json]
```

### 参数

| 参数 | 说明 |
|------|------|
| `config` | YAML 文件路径，或目录（递归扫描 `*.yml`/`*.yaml`） |
| `--level` | 最低显示级别（默认 `info`，只看错误用 `error`） |
| `--format` | 输出格式（默认 `text`） |

### 示例

```bash
# 分析单个文件
python -m lambdagent lint agent-config.yml

# 只显示错误
python -m lambdagent lint agent-config.yml --level error

# 扫描目录下所有配置
python -m lambdagent lint configs/

# JSON 输出（CI/CD 集成）
python -m lambdagent lint agent-config.yml --format json
```

输出示例：
```
lambdagent lint: agent-config.yml
============================================================
  [x] [ERROR] [L004] type=react but no 'terminate' in localTools
    Lambda: Y combinator has no base case -> infinite loop
  [!] [WARN ] [S002] Agent has tools but no guard config. Add guard.dangerousCommandBlock for safety.
    Lambda: Unguarded tool access = untyped β-reduction (no dependent type constraint)
  [i] [INFO ] [L015] Memory enabled: strategy=redis
    Lambda: Gamma' = Gamma union store(redis)
──────────────────────────────────────────────────────
  1 error(s), 1 warning(s), 1 info(s)
```

### lint 规则速查

**功能规则 (L001-L026)**

| 规则 | 级别 | 说明 |
|------|------|------|
| L001 | ERROR | 缺少 `type` 字段 |
| L002 | ERROR | 无效的 `type` 值 |
| L003 | ERROR | 缺少 `systemPrompt` |
| L004 | ERROR | `react` 类型但无 `terminate` 工具（Y 组合子无 base case） |
| L005 | WARN | 无 MCP 工具配置 |
| L010 | INFO | 温度为 0（确定性输出） |
| L015 | INFO | Memory 策略信息 |

**安全规则 (S001-S003)**

| 规则 | 级别 | 说明 |
|------|------|------|
| S001 | ERROR/WARN | `maxSteps` 过大（>1000 ERROR，>100 WARN） |
| S002 | WARN | 有工具但无 Guard 配置 |
| S003 | WARN | SandboxPolicy 过于宽松 |

---

## trace — 查看 β-规约追踪

查看和分析之前保存的执行追踪（由 `run --trace-file` 生成）。

```bash
python -m lambdagent trace <trace.json> [--step N] [--timeline]
```

### 参数

| 参数 | 说明 |
|------|------|
| `file` | trace JSON 文件路径 |
| `--step N` | 查看第 N 步详情 |
| `--timeline` | 时间线视图 |

### 默认视图（全部步骤）

```bash
python -m lambdagent trace trace.json
```

输出：
```
  β[0] think (2312ms): 帮我写快速排序... → 我需要思考...
  β[1] Tool:search (450ms): 快速排序算法 → 快速排序是一种分治算法...
  β[2] think (1803ms): 根据搜索结果... → 我来写代码...
  β[3] Tool:terminate (1ms): 返回最终答案 → def quicksort...

Total: 4 β-reductions, 4.6s
```

### 查看单步详情

```bash
python -m lambdagent trace trace.json --step 1
```

输出：
```
β[1] Tool:search
  Duration: 450ms
  Model:    N/A
  Tokens:   N/A
  Input:    快速排序算法
  Output:   快速排序是一种分治算法，它选择一个基准元素...
```

### 时间线视图

```bash
python -m lambdagent trace trace.json --timeline
```

输出：
```
Time ──────────────────────────────────────────→
   0.0s ├████████████████████████ think (2312ms)
   2.3s ├█████ Tool:search (450ms)
   2.8s ├██████████████████ think (1803ms)
   4.6s ├ Tool:terminate (1ms)
   4.6s ┤ END
```

---

## lambda — 导出 Lambda 表达式

将 YAML 配置导出为形式化的 Lambda 表达式，展示 Agent 的数学结构。

```bash
python -m lambdagent lambda <config.yml> [--format human|formal|json]
```

### 参数

| 参数 | 说明 |
|------|------|
| `config` | YAML 配置文件路径 |
| `--format` | `human`（默认，可读），`formal`（形式化），`json` |

### 示例

```bash
python -m lambdagent lambda agent-config.yml
```

输出（ReAct Agent）：
```
my-agent =
    Y_10(λself. λstate.
      let t = (λx. LLM_{anthropic/claude-sonnet-4-20250514, ⊕_0}("You are a helpful..."))(state) in
      CASE (classify t) [
        ("search", λx. MCP("mcp-server", "search", x))
        ("terminate", λx. x)  ← base case
      ] >> λobs.
      IF (obs = t) THEN t ELSE self(state ⊕ format(t, obs))
    )
```

输出（Chain Agent）：
```
report-pipeline =
    >> Lam("extract", "Extract key facts from the input....")
    >> Lam("analyze", "Analyze the facts and identify patter...")
    >> Lam("report", "Write a structured report....")
```

JSON 格式：
```bash
python -m lambdagent lambda agent-config.yml --format json
```

---

## tools — 列出和测试工具

列出 Agent 配置中的所有可用工具，检查 MCP 服务器连接状态。

```bash
python -m lambdagent tools <config.yml> [--test TOOL INPUT] [--discover SERVER]
```

### 参数

| 参数 | 说明 |
|------|------|
| `config` | YAML 配置文件路径 |
| `--test TOOL INPUT` | 测试指定工具 |
| `--discover SERVER` | 发现 MCP 服务器上的工具 |

### 示例

```bash
python -m lambdagent tools agent-config.yml
```

输出：
```
Tools for my-agent:
────────────────────────────────────────────────────────────
  [MCP]   search                         mcp-server
  [MCP]   read_file                      mcp-server
  [Local] terminate                      (λx.x) base case

MCP endpoints:
  mcp-server: http://localhost:3001/mcp
    Status: ✓ reachable (23ms)
```

---

## version — 版本信息

```bash
python -m lambdagent version
```

```
lambdagent v2.0.0
Lambda Calculus Agent DSL
11 core constructs — strict lambda correspondence
```

---

## 高级用法

### 1. JSON 输出用于程序化处理

```bash
# 完整 JSON 输出（result + trace + stats）
python -m lambdagent run agent.yml "task" --format json | jq '.stats'

# lint 结果 JSON（CI/CD 中判断是否阻塞部署）
python -m lambdagent lint agent.yml --format json | jq '[.[] | select(.level=="ERROR")] | length'
```

### 2. 管道编排 Agent

```bash
# Agent A 的输出作为 Agent B 的输入（CLI 层面的 >> 组合）
python -m lambdagent run extract.yml "raw data" --quiet | \
  python -m lambdagent run analyze.yml - --quiet | \
  python -m lambdagent run report.yml - --quiet > report.txt
```

### 3. 批量处理

```bash
# 对多个输入批量执行
cat inputs.txt | while read line; do
  python -m lambdagent run agent.yml "$line" --quiet >> results.txt
done

# lint 整个目录
python -m lambdagent lint configs/ --level error
```

### 4. 工具注入 + ReAct 实战

```bash
# 日志分析 Agent（注入 grep + wc 工具）
python -m lambdagent run react-agent.yml "分析今天的错误日志" \
  --tool grep="grep ERROR /var/log/app.log" \
  --tool count="wc -l /var/log/app.log" \
  --tool tail="tail -20 /var/log/app.log" \
  --trace

# 代码搜索 Agent（参数化工具）
python -m lambdagent run react-agent.yml "找出所有使用了 deprecated API 的文件" \
  --tool search="grep -rn {} src/" \
  --tool find="find src/ -name {} -type f" \
  --max-steps 15
```

### 5. 模型对比

```bash
# 同一任务，不同模型
python -m lambdagent run agent.yml "写一首关于AI的诗" --model claude-sonnet-4-20250514 --quiet > claude.txt
python -m lambdagent run agent.yml "写一首关于AI的诗" --model gpt-4o --quiet > gpt4.txt
diff claude.txt gpt4.txt
```

---

## YAML 配置参考

### 最小配置

```yaml
type: simple
systemPrompt: "You are a helpful assistant."
model:
  name: claude-sonnet-4-20250514
```

### Provider 切换（YAML 配置）

通过 `model.provider` 字段在统一的 Provider 系统中切换后端：

```yaml
# Claude Code — 无需 API Key，调用 Claude Code CLI
model:
  provider: claude-code
  name: sonnet

# Anthropic API — 需要 ANTHROPIC_API_KEY
model:
  provider: anthropic
  name: claude-sonnet-4-20250514

# Ollama 本地模型 — 无需 API Key
model:
  provider: ollama
  name: qwen2.5:7b

# OpenAI — 需要 OPENAI_API_KEY
model:
  provider: openai
  name: gpt-4o

# DashScope (阿里云) — 需要 DASHSCOPE_API_KEY
model:
  provider: dashscope
  name: qwen-max
```

统一 Provider 列表：`claude-code`, `anthropic`, `ollama`, `openai`, `dashscope`

### 完整 ReAct Agent

```yaml
agentId: research-agent
name: ResearchAgent
type: react
systemPrompt: |
  You are a research assistant. Use tools to find information,
  then synthesize a comprehensive answer.

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

react:
  maxSteps: 15
  toolTimeout: 30
  observationEnabled: true
  verbose: false

mcp:
  onlineTool:
    my-server:
      - search
      - read_file
  localTools:
    - terminate
  policy:
    mode: auto           # auto | force | intelligence | disable
    retryOnFail: 1

guard:
  dangerousCommandBlock: true
  highRiskConfirmation: false
  maxOutputLength: 10000
  validator: "len(x) > 10"
  retry: 1
  fallback: last

# --strict-mcp-config: MCP 隔离模式
# 当设置时，Agent 只能访问配置中声明的 MCP 工具，不继承全局工具
strictMcpConfig: true   # 等同于 CLI 的 --strict-mcp-config 标志

memory:
  enabled: true
  strategy: local
  size: 20
  ttl: 3600

app:
  mcp:
    custom:
      nodes:
        my-server:
          url: http://localhost:3001
          endpoint: /mcp
          timeout: 30
```

### Agent 类型速查

| type | Lambda 对应 | 说明 |
|------|-------------|------|
| `simple` | `λx. LLM(x)` | 单步 LLM 调用 |
| `react` | `Y_n(λself.λstate. think >> route >> observe)` | ReAct 循环（工具调用） |
| `chain` | `f >> g >> h` | 顺序执行管道 |
| `router` | `CASE (classifier x) [(l₁, a₁), ...]` | 分类器路由 |
| `parallel` | `(f \| g) >> merge` | 并行执行 + 合并 |

---

## 退出码

| 退出码 | 说明 |
|--------|------|
| `0` | 成功 |
| `1` | 一般错误（输入缺失、工具注入失败等） |
| `3` | lint 存在 ERROR 级别问题 |
| `4` | 文件未找到 |
| `130` | 用户中断（Ctrl+C） |

---

# Part II — agentpaas CLI

> AgentPaaS 平台管理 CLI。管理 API 服务器、租户、Agent 部署、运行监控和 LLM Provider。

## 目录（agentpaas）

- [快速开始](#快速开始)
- [config — CLI 配置](#config--cli-配置)
- [serve — 启动 API 服务器](#serve--启动-api-服务器)
- [create-tenant — 创建租户](#create-tenant--创建租户)
- [agent — Agent 管理](#agent--agent-管理)
- [chat — 交互式对话](#chat--交互式对话)
- [run — 执行 Agent（远程）](#run--执行-agent远程)
- [status — 平台状态](#status--平台状态)
- [health — Agent 健康度](#health--agent-健康度)
- [runs — 运行历史](#runs--运行历史)
- [trace — 运行追踪](#trace--运行追踪)
- [key — API Key 管理](#key--api-key-管理)
- [usage / metrics — 计费与指标](#usage--metrics--计费与指标)
- [provider — LLM Provider 管理](#provider--llm-provider-管理)

---

## 快速开始

```bash
# 1. 启动 API 服务器（开发模式）
python -m agentpaas serve --dev

# 2. 创建租户并获取 API Key
python -m agentpaas create-tenant --name "My Org"
# 输出：
#   Tenant: tn_xxxx
#   API Key: ap_xxxx
#   API key saved to config. Ready to use.

# 3. 创建 Agent（从 YAML 配置）
python -m agentpaas agent create --name my-agent --config agent-config.yml

# 4. 执行 Agent
python -m agentpaas run ag_xxxx "帮我写快速排序"

# 5. 查看状态
python -m agentpaas status
```

---

## config — CLI 配置

配置 CLI 连接参数（服务器地址、API Key）。配置保存在 `~/.agentpaas/config.json`。

```bash
# 查看当前配置
python -m agentpaas config show

# 设置服务器地址
python -m agentpaas config set --server http://your-server:8000

# 设置 API Key
python -m agentpaas config set --api-key ap_your_api_key_here

# 同时设置
python -m agentpaas config set --server http://prod:8000 --api-key ap_xxxx
```

输出示例：
```
Server:  http://localhost:8000
API Key: ap_abcdef12...
Config:  /Users/you/.agentpaas/config.json
```

---

## serve — 启动 API 服务器

启动 AgentPaaS FastAPI 服务器。

```bash
python -m agentpaas serve [--host HOST] [--port PORT] [--dev]
```

| 参数 | 说明 |
|------|------|
| `--host` | 绑定地址（默认 `0.0.0.0`） |
| `--port` | 端口（默认 `8000`） |
| `--dev` | 开发模式（热重载） |

### 示例

```bash
# 开发模式（自动重载）
python -m agentpaas serve --dev

# 生产模式（需要设置 AGENTPAAS_MASTER_KEY）
export AGENTPAAS_MASTER_KEY=$(python -c "import secrets; print(secrets.token_hex(32))")
python -m agentpaas serve --port 8080

# 启动后可访问
#   API 文档: http://localhost:8000/docs
#   健康检查: http://localhost:8000/health
```

---

## create-tenant — 创建租户

直接操作数据库创建租户（不需要 API 服务器运行）。自动生成 admin 用户和 API Key。

```bash
python -m agentpaas create-tenant --name "组织名" [--plan free|pro] [--email admin@org.com]
```

| 参数 | 说明 |
|------|------|
| `--name` | 租户名称（必填） |
| `--plan` | 套餐（`free`/`pro`，默认 `free`） |
| `--email` | 管理员邮箱 |

### 示例

```bash
python -m agentpaas create-tenant --name "Research Lab" --plan pro --email admin@lab.edu
```

输出：
```
Tenant: tn_a1b2c3d4
API Key: ap_e5f6g7h8i9j0k1l2m3n4o5p6
API key saved to config. Ready to use.
```

> API Key 只显示一次，请安全保存。Key 已自动写入 `~/.agentpaas/config.json`。

---

## agent — Agent 管理

Agent 的完整生命周期管理：创建、查看、更新、删除、版本管理。

### agent list — 列出所有 Agent

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

输出：
```
ID               Name                  Ver Status       Updated
--------------------------------------------------------------------------------
ag_abc123        ResearchBot             3 active       2026-04-01T10:30:00
ag_def456        CodeReviewer            1 active       2026-03-28T14:20:00
```

### agent create — 创建 Agent

```bash
python -m agentpaas agent create --name <name> [--config <yaml>] [--prompt <text>] [--description <text>] [--tags <t1,t2>]
```

| 参数 | 说明 |
|------|------|
| `--name` | Agent 名称（必填） |
| `--config` | YAML 配置文件路径 |
| `--prompt` | 快速创建：直接指定 system prompt（不用 YAML） |
| `--description` | Agent 描述 |
| `--tags` | 逗号分隔的标签 |

```bash
# 从 YAML 创建
python -m agentpaas agent create --name research-bot --config research-agent.yml --tags "research,rag"

# 快速创建（无需 YAML）
python -m agentpaas agent create --name quick-helper --prompt "You are a helpful coding assistant."
```

输出：
```
Agent created: ag_abc123
Version: 1
Endpoint: /api/v1/agents/ag_abc123
```

### agent get — 查看 Agent 详情

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

输出（JSON）：
```json
{
  "id": "ag_abc123",
  "name": "ResearchBot",
  "current_version": 3,
  "status": "active",
  "config": { "type": "react", "systemPrompt": "..." },
  "tags": ["research", "rag"]
}
```

### agent update — 更新配置

```bash
python -m agentpaas agent update ag_abc123 --config new-config.yml --changelog "增加搜索工具"
```

> 自动版本递增。如果配置内容未变化，不会创建新版本。

### agent rollback — 回滚版本

```bash
python -m agentpaas agent rollback ag_abc123 --version 2
```

### agent versions — 查看版本历史

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

输出：
```
 Ver Current  Created              Changelog
------------------------------------------------------------
   3 *        2026-04-01T10:30:00  增加搜索工具
   2          2026-03-30T09:00:00  优化 prompt
   1          2026-03-28T14:20:00  Initial version
```

### agent update — 更新 Agent 配置

更新已部署 Agent 的 YAML 配置，自动递增版本号。

```bash
python -m agentpaas agent update <agent_id> --config <new-config.yml> [--changelog "变更说明"]
```

| 参数 | 说明 |
|------|------|
| `agent_id` | Agent ID |
| `--config` | 新的 YAML 配置文件 |
| `--changelog` | 版本变更说明 |

```bash
# 更新配置（自动版本递增）
python -m agentpaas agent update ag_abc123 --config agent-v2.yml --changelog "切换到 claude-code provider"

# 切换 provider（修改 YAML 中的 model.provider 后更新）
python -m agentpaas agent update ag_abc123 --config agent-claude-code.yml --changelog "无需 API Key"
```

> 如果配置内容未变化，不会创建新版本。更新后可用 `agent versions` 查看历史，用 `agent rollback` 回退。

### agent delete — 删除 Agent

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

> 软删除，不会物理删除数据。

---

## chat — 交互式对话

通过 PaaS API 与已部署的 Agent 进行交互式多轮对话。支持流式输出（SSE）。

```bash
python -m agentpaas chat [target]
```

| 参数 | 说明 |
|------|------|
| `target` | Agent ID（`ag_xxx`）或 Agent 名称。省略则自动选择 |

### 基本用法

```bash
# 按名称对话（支持模糊匹配）
agentpaas chat lambda

# 按 ID 对话
agentpaas chat ag_abc123

# 省略 target，自动选择唯一 Agent 或交互式列表
agentpaas chat
```

### 使用 claude-code provider

如果 Agent 的 YAML 配置中指定了 `provider: claude-code`，`agentpaas chat` 会使用 Claude Code 后端，无需任何 API Key：

```yaml
# agent-config.yml
agentId: lambda
name: lambda
type: react
model:
  provider: claude-code
  name: sonnet
systemPrompt: "You are a helpful assistant."
```

```bash
# 部署后直接对话，不需要 API Key
agentpaas agent create --name lambda --config agent-config.yml
agentpaas chat lambda
```

### 会话内命令

| 命令 | 说明 |
|------|------|
| `exit` / `quit` / `bye` | 退出对话 |
| `history` | 查看对话历史 |

### 示例会话

```
╔══════════════════════════════════════════════════════════╗
║  lambda — via AgentPaaS                                 ║
║  Agent: ag_abc123  Version: 3                           ║
╠══════════════════════════════════════════════════════════╣
║  输入消息开始对话，exit 退出，history 查看历史          ║
╚══════════════════════════════════════════════════════════╝

You: 帮我写一个快速排序
Agent: [streaming response...]
```

---

## run — 执行 Agent（远程）

通过 API 远程执行 Agent。

```bash
python -m agentpaas run <agent_id> [input] [--input-file FILE] [--temperature FLOAT] [--max-steps INT] [--stream]
```

| 参数 | 说明 |
|------|------|
| `agent_id` | Agent ID（如 `ag_abc123`） |
| `input` | 输入文本 |
| `--input-file` | 从文件读取输入 |
| `--temperature` | 覆盖温度 |
| `--max-steps` | 覆盖最大步数 |
| `--stream` | 流式输出（预留） |

### 示例

```bash
# 直接输入
python -m agentpaas run ag_abc123 "帮我写一个快速排序"

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

# 覆盖参数
python -m agentpaas run ag_abc123 "创意写作" --temperature 0.8 --max-steps 20
```

输出：
```
Running agent ag_abc123...

--- Result (3.2s) ---
def quicksort(arr):
    if len(arr) <= 1:
        return arr
    pivot = arr[len(arr) // 2]
    ...

--- Stats ---
  Run ID:    run_xyz789
  Tokens:    1523 (in: 423, out: 1100)
  Steps:     4
  Duration:  3215ms
```

---

## status — 平台状态

查看平台总览或单个 Agent 的运行状态。

```bash
# 平台总览
python -m agentpaas status

# 所有 Agent 状态（含健康度评分）
python -m agentpaas status agents [--sort last_run|score|runs]

# 单个 Agent 详情
python -m agentpaas status ag_abc123
```

### 平台总览

```bash
python -m agentpaas status
```

输出：
```
=== AgentPaaS Status ===
  Active agents:  5
  Total runs:     1247
  Running now:    2
  Success rate:   94.3%
  Avg latency:    2341ms
  Total tokens:   4523100
```

### Agent 状态仪表板

```bash
python -m agentpaas status agents
```

输出：
```
ID               Name              Score  Runs   Fail  Succ%  Lat(ms) Last Run
----------------------------------------------------------------------------------------------------
ag_abc123        ResearchBot       [+] 92    523     12    97.7%     2100 2026-04-01T10:30
ag_def456        CodeReviewer      [~] 71    200     35    82.5%     4500 2026-04-01T09:15
ag_ghi789        Translator        [!] 45     50     22    56.0%     8200 2026-03-30T18:00
```

> 健康度符号: `+` = healthy, `~` = degraded, `!` = warning, `X` = critical

---

## health — Agent 健康度

查看单个 Agent 的详细健康评分和各维度指标。

```bash
python -m agentpaas health ag_abc123
```

输出：
```
[OK] Agent ag_abc123 health: 92/100 (healthy)
  success_rate: 97.7%
  avg_latency_ms: 2100
  error_rate_1h: 1.2%
  p99_latency_ms: 5800
```

---

## runs — 运行历史

查看 Agent 的运行历史记录。

```bash
python -m agentpaas runs <agent_id> [--limit N]
```

```bash
python -m agentpaas runs ag_abc123 --limit 10
```

输出：
```
Run ID           Status      Dur(ms)  Steps   Tokens Created
--------------------------------------------------------------------------------
run_001          completed      2100      4     1523 2026-04-01T10:30:00
run_002          completed      1800      3     1200 2026-04-01T09:15:00
run_003          failed         5200      7     3100 2026-04-01T08:00:00
```

---

## trace — 运行追踪

查看单次运行的详细执行追踪（JSON 输出）。

```bash
python -m agentpaas trace <run_id>
```

```bash
python -m agentpaas trace run_001
```

输出完整的 run 记录（JSON），包含 input、output、status、duration、tokens 等。

---

## key — API Key 管理

### key create — 创建新 Key

```bash
python -m agentpaas key create --name <name> [--scopes <s1,s2>] [--rate-limit N]
```

| 参数 | 说明 |
|------|------|
| `--name` | Key 名称 |
| `--scopes` | 权限范围（逗号分隔，默认 `agents:read,agents:execute`） |
| `--rate-limit` | 每分钟请求限制（默认 60） |

```bash
# 创建只读 Key
python -m agentpaas key create --name readonly-key --scopes "agents:read"

# 创建高频 Key
python -m agentpaas key create --name batch-key --scopes "agents:read,agents:execute" --rate-limit 600
```

输出：
```
Key created: key_abc123
API Key: ap_xxxxxxxxxxxxxxxxxxxxxxxx
Store this key securely!
```

### key list — 列出所有 Key

```bash
python -m agentpaas key list
```

输出：
```
ID               Prefix     Name             Status   Last Used
----------------------------------------------------------------------
key_abc123       ap_abcd    admin            active   2026-04-01T10:30
key_def456       ap_efgh    readonly-key     active   2026-03-28T14:20
```

### key revoke — 吊销 Key

```bash
python -m agentpaas key revoke key_def456
```

---

## usage / metrics — 计费与指标

### usage — 使用量查询

```bash
python -m agentpaas usage [--group-by agent|model|day]
```

```bash
# 按 Agent 统计
python -m agentpaas usage --group-by agent

# 按模型统计
python -m agentpaas usage --group-by model

# 按日统计
python -m agentpaas usage --group-by day
```

### metrics — 平台指标

```bash
python -m agentpaas metrics
```

输出平台级别的聚合指标（JSON 格式）。

---

## provider — LLM Provider 管理

管理 LLM 服务提供商配置。配置保存在 `~/.agentpaas/providers.json`，本地操作不需要 API 服务器。

### 预置 Provider

| ID | 名称 | 类型 | 环境变量 |
|-----|------|------|---------|
| `claude-code` | Claude Code (Max Plan) | claude_code | —（无需 API Key） |
| `anthropic` | Anthropic Claude | anthropic | `ANTHROPIC_API_KEY` |
| `openai` | OpenAI GPT | openai | `OPENAI_API_KEY` |
| `dashscope` | DashScope (Qwen) | openai_compatible | `DASHSCOPE_API_KEY` |
| `deepseek` | DeepSeek | openai_compatible | `DEEPSEEK_API_KEY` |
| `zhipu` | Zhipu AI (GLM) | openai_compatible | `ZHIPU_API_KEY` |
| `moonshot` | Moonshot (Kimi) | openai_compatible | `MOONSHOT_API_KEY` |
| `ollama` | Ollama (Local) | openai_compatible | — |

> **统一 Provider 系统**：五个核心 Provider — `claude-code`, `anthropic`, `ollama`, `openai`, `dashscope`。`claude-code` 通过 Claude Code CLI 直接调用，不需要任何 API Key。

### provider list — 列出所有 Provider

```bash
python -m agentpaas provider list
```

输出：
```
ID              Name                      Base URL                                      Status
----------------------------------------------------------------------------------------------------
anthropic       Anthropic                 https://api.anthropic.com                     [OK]
openai          OpenAI                    https://api.openai.com/v1                     [NO KEY (OPENAI_API_KEY)]
dashscope       DashScope (Qwen)          https://dashscope.aliyuncs.com/compatible-mod [OK]
ollama          Ollama (Local)            http://localhost:11434/v1                      [OK]
```

### provider add — 添加/更新 Provider

```bash
python -m agentpaas provider add <id> [--api-key KEY] [--base-url URL] [--name NAME] [--models m1,m2]
```

```bash
# 配置 DashScope API Key
python -m agentpaas provider add dashscope --api-key sk-xxxx

# 添加自定义 Provider
python -m agentpaas provider add my-llm \
  --name "My LLM Service" \
  --base-url https://my-llm.example.com/v1 \
  --api-key sk-xxxx \
  --models "my-model-7b,my-model-72b"
```

### provider test — 测试连接

```bash
python -m agentpaas provider test <id> [--api-key KEY] [--model MODEL] [--prompt TEXT]
```

```bash
# 测试 Anthropic（使用环境变量中的 Key）
python -m agentpaas provider test anthropic

# 测试指定模型
python -m agentpaas provider test dashscope --model qwen-max

# 自定义测试 prompt
python -m agentpaas provider test openai --prompt "Say hello in Chinese"
```

输出：
```
Testing dashscope (qwen3-max-2026-01-23)...
OK (1.2s): 你好！有什么可以帮助你的吗？
```

### provider models — 查看可用模型

```bash
python -m agentpaas provider models <id>
```

```bash
python -m agentpaas provider models dashscope
```

输出（从 API 动态查询）：
```
  qwen-max
  qwen-plus
  qwen-turbo
  qwen3-max-2026-01-23
```

### provider remove — 移除 Provider

```bash
python -m agentpaas provider remove my-llm
```

---

## 典型工作流

### 1. 本地开发流程

```bash
# 启动服务
python -m agentpaas serve --dev &

# 创建租户
python -m agentpaas create-tenant --name dev

# 配置 LLM Provider
python -m agentpaas provider add dashscope --api-key sk-xxxx
python -m agentpaas provider test dashscope

# 编写 + lint Agent 配置
python -m lambdagent lint my-agent.yml
python -m lambdagent compile my-agent.yml --validate

# 本地测试（直接执行，不经过 PaaS）
python -m lambdagent run my-agent.yml "test input" --trace

# 部署到 PaaS
python -m agentpaas agent create --name my-agent --config my-agent.yml

# 远程执行
python -m agentpaas run ag_xxxx "production input"

# 监控
python -m agentpaas status agents
python -m agentpaas health ag_xxxx
```

### 2. 版本迭代流程

```bash
# 修改配置后更新
python -m lambdagent lint my-agent-v2.yml
python -m agentpaas agent update ag_xxxx --config my-agent-v2.yml --changelog "优化 prompt"

# 查看版本
python -m agentpaas agent versions ag_xxxx

# 测试新版本
python -m agentpaas run ag_xxxx "test input"

# 如果有问题，回滚
python -m agentpaas agent rollback ag_xxxx --version 1
```

### 3. 运维排查流程

```bash
# 查看整体状态
python -m agentpaas status

# 找到异常 Agent
python -m agentpaas status agents --sort score

# 查看健康详情
python -m agentpaas health ag_xxxx

# 查看最近运行
python -m agentpaas runs ag_xxxx --limit 5

# 查看失败运行的详情
python -m agentpaas trace run_failed_xxx

# 查看使用量
python -m agentpaas usage --group-by agent
```