evilsocket/nerve · 上手攻略

• 仓库：evilsocket/nerve
• 链接：https://github.com/evilsocket/nerve
• 分类：AI · LLM Agent 开发框架
• 作者：Jay
• 更新：2026-08-16

是什么

Nerve（The Simple Agent Development Kit）是一个用 YAML + CLI 构建、运行、评测和编排 LLM Agent 的轻量框架。它的核心理念是声明式 Agent：用 YAML 定义 system prompt、task、tools 和 variables，一个文件搞定一个 Agent，再通过 nerve CLI 驱动执行。Built on LiteLLM，支持 OpenAI/Anthropic/Ollama 等数十种模型，一行配置切换后端。

技术栈：Python 3.10+ / LiteLLM / Jinja2 模板 / MCP（Model Context Protocol）原生支持 / GPL-3 许可证。

解决什么问题

1. 快速定义 Agent：无需写 Python 代码，YAML 文件声明式定义 Agent 行为
2. 多模型对比评测：同一个 Agent 换一行配置就能在 GPT-4o / Claude / Llama 等模型上跑，对比效果差异
3. 结构化评测：内置评测模式（Evaluation Mode），用 YAML/Parquet/文件夹定义测试用例集，跑回归测试
4. MCP 原生集成：首个在 YAML 中声明式定义 MCP Server 的框架，同时充当 Client 和 Server
5. 可复现执行：trace/replay 机制，完整记录 Agent 执行轨迹并支持回放调试
6. Workflow 编排：将多个 Agent 串成线性 Pipeline，共享上下文

快速安装

pip（推荐）

pip install nerve-adk

# 升级
pip install --upgrade nerve-adk

# 卸载
pip uninstall nerve-adk

Python 3.10+ required. （版本号未经 pip 页面核验，标注待验）

Docker

docker run -it --network=host -v ./examples:/root/.nerve/agents evilsocket/nerve -h

从 GitHub 安装已有 Agent

nerve install evilsocket/changelog
nerve run changelog

核心用法

创建第一个 Agent（交互式引导）

nerve create new-agent

引导过程依次询问： 1. 保存位置（$HOME/.nerve/agents/<name>/） 2. System prompt（可写字符串，或用 @filename 从 $HOME/.nerve/prompts/ 加载） 3. Task 描述（Jinja2 模板语法） 4. 工具命名空间（从 built-in namespaces 选）

生成文件 $HOME/.nerve/agents/new-agent/agent.yml：

agent: You are a helpful assistant.
task: Make an HTTP request to {{ url }}
using:
  - shell
  - task

运行 Agent

nerve run new-agent --url cnn.com

覆盖默认变量：--url 覆盖 YAML 中的 defaults.url。

交互式步进模式

nerve run new-agent -i
# 可用命令：step/s/Enter（下一步）/ continue/c（跑完）/ view/v（查看状态）/ quit/q/exit

完整 Agent YAML 字段

agent: You are a helpful assistant.
task: Make an HTTP request to {{ url }}
generator: openai/gpt-4o        # 可选，默认 gpt-4o-mini
reasoning: medium               # 可选：low/medium/high（需要模型支持）
description: "This agent makes HTTP requests"
version: "1.0.0"
requires: ">=1.2.0"             # 可选，最小 Nerve 版本要求

defaults:                        # 变量默认值
  url: "https://example.com"
  timeout: 30

jail:                            # 可选，文件系统访问限制
  filesystem:
    - "/allowed/path"
    - "{{ target_dir }}"

limits:                          # 可选，执行限制
  max_steps: 100
  max_cost: 5.0
  timeout: 300                   # 秒

using:
  - shell
  - task

内置变量（Jinja2 模板）

日期时间：{{ CURRENT_DATE }} / {{ CURRENT_TIME }} / {{ CURRENT_DATETIME }} / {{ CURRENT_TIMESTAMP }}

平台信息：{{ USERNAME }} / {{ PLATFORM }} / {{ ARCHITECTURE }} / {{ PYTHON_VERSION }} / {{ HOME }}

网络：{{ LOCAL_IP }} / {{ PUBLIC_IP }} / {{ HOSTNAME }}

随机：{{ RANDOM_INT }} / {{ RANDOM_HEX }} / {{ RANDOM_FLOAT }} / {{ RANDOM_STRING }}

剪贴板：{{ CLIPBOARD }}

切换模型

# 环境变量（全局默认）
export NERVE_GENERATOR=anthropic/claude-3-7-sonnet
nerve run agent

# CLI 参数（一次性）
nerve run -g "ollama/llama3.2?temperature=0.9" agent

# YAML 内直接写
generator: "anthropic/claude"

定义自定义工具

Shell 工具（直接在 YAML 中）：

tools:
  - name: get_weather
    description: Get the current weather in a given place.
    arguments:
      - name: place
        description: The place to get the weather of.
        example: Rome
    tool: curl wttr.in/{{ place }}

Python 工具（tools.py 与 agent.yml 同目录）：

# new-agent/tools.py
import typing as t

def read_webcam_image(
    foo: t.Annotated[str, "Describe arguments to the model like this."]
) -> dict[str, str]:
    """Reads an image from the webcam."""
    base64_image = '...'
    return {
        "type": "image_url",
        "image_url": {"url": f"data:image/jpeg;base64,{base64_image}"},
    }

评测模式（Evaluation Mode）

nerve eval path/to/evaluation --output results.json
nerve eval path/to/evaluation --output results.json --trace eval-trace.jsonl

YAML 测试用例格式（小型套件）：

- level1:
  program: "A# #A"
- level2:
  program: "A# #B B# #A"

Parquet 格式（大规模结构化数据集，如 MMLU）：

task: >
  ## Question

  {{ question }}

  Use the `select_choice` tool to pick the right answer:
  {% for choice in choices %}
  - [{{ loop.index0 }}] {{ choice }}
  {% endfor %}

评测结果写入 .json，包含：case id / 成功失败状态 / 运行时长 / Agent 输出 / 工具调用记录。

Trace（执行轨迹记录与回放）

# 记录
nerve run agent --trace trace.jsonl

# 回放（正常速度）
nerve play trace.jsonl

# 快进（跳过延迟）
nerve play trace.jsonl -f

JSONL 格式，每行一个事件：task_started / step_started / tool_called / variable_change / task_complete 等。

Workflow（多 Agent 流水线）

将多个 Agent 按顺序串起来，共享上下文：

nerve run examples/recipe-workflow --food pizza

详见 workflows.md。

追踪集成（LiteLLM Observability）

支持 Langfuse / OpenTelemetry 等，需安装对应依赖并设置环境变量：

pip install langfuse

export LANGFUSE_PUBLIC_KEY="..."
export LANGFUSE_SECRET_KEY="..."
export LANGFUSE_HOST="..."

nerve run <agent-name> --litellm-tracing langfuse

典型适用场景

1. 快速原型验证：想验证一个 LLM 自动化流程是否可行，用 YAML 5 分钟搭一个 Agent，不需要写 Python
2. 模型对比评测：同一套 Agent 定义在 GPT-4o / Claude 3.5 / Llama 3.1 上跑，对比质量/速度/成本
3. 回归测试：每次改 prompt 或工具定义后，跑评测套件确认关键 case 通过
4. 多 Agent 协作：Workflow 串接多个 Agent（数据采集 → 分析 → 报告），各步骤共享状态
5. MCP 生态接入：用 Nerve 作为 MCP Client 消费远程工具，或将 Nerve Agent 暴露为 MCP Server 给其他 Agent 调用

坑与注意

1. 默认模型是 GPT-4o-mini：未设置 NERVE_GENERATOR 时使用 OpenAI GPT-4o-mini，需注意 API 费用；切换模型推荐用 -g 参数一次性覆盖
2. Ollama 本地模型：需指定 api_base 参数，如 nerve run -g "ollama/llama3.2?api_base=http://1.2.3.4:11434" agent
3. 文件路径约定：Agent 优先从 $HOME/.nerve/agents/ 加载，其次才是当前工作目录；命名冲突时优先前者
4. Python 工具的注册：需要 tools.py 与 agent.yml 在同一目录；函数签名需要类型注解，否则 Nerve 无法解析参数
5. 评测结果无内置聚合：结果写入 JSON 后需自行写脚本聚合（如计算 pass rate），Nerve 本身不做统计分析
6. MCP YAML 定义语法：MCP Server 在 YAML 中的声明方式较新颖（自称"first framework"），实际稳定性和生态成熟度待验
7. 许可证是 GPL-3：若在商业产品中集成，需注意传染性；作为工具使用不受影响

与同类对比

Nerve 的差异化定位：最轻量的声明式 Agent 框架，用 YAML 而非 Python 代码定义 Agent，适合技术用户快速原型验证；但复杂 Agent 逻辑（分支/循环/记忆）相比 LangChain 等欠丰富。

一句话推荐结论

如果你想要一个比 LangChain 更轻、5 分钟上手、不写 Python 就能跑 LLM Agent 的工具，Nerve 是当前最干净的选项——尤其是自带评测模式和 MCP 原生支持，在验证 Agent 逻辑正确性上比大多数同类省心。

原始链接：https://github.com/evilsocket/nerve