Harbor 集成

使用 LangSmith 在一个地方运行、跟踪、比较 Agent 评估并计算成本，并将 Harbor 作为执行层。Harbor 是一个用于在沙箱环境中评估和优化 Agent 及语言模型的框架，由 Terminal-Bench 的创建者开发。它会在隔离容器中运行每次试验，因此你可以同时在多个环境中并行执行评估和运行任务。 LangSmith 在以下三个方面与 Harbor 集成：

LangSmith 评估：使用 --plugin langsmith 将每个 Harbor 作业作为实验记录到 LangSmith。
Deep Agents：使用 --agent langgraph 将 LangGraph 或 Deep Agents 应用作为 Harbor Agent 运行。
沙箱：使用 --env langsmith 在 LangSmith 沙箱中运行每次 Harbor 试验。

本页面介绍 Harbor 中与 LangSmith 相关的标志。完整的 CLI 用法请运行 harbor run --help，或参阅 Harbor 文档。

前置条件

一个 LangSmith 账户和一个 API 密钥。
Python 3.12 或更高版本，以及 pip。
Agent 所调用模型对应的提供商 API 密钥，例如 ANTHROPIC_API_KEY。

安装

使用 langsmith extra 安装 Harbor。该 extra 包含 LangSmith 插件、环境和 Agent 所使用的 harbor-langsmith 包：

pip install "harbor[langsmith]"

身份验证

Harbor 使用你的 LangSmith 凭据进行身份验证。设置 API 密钥：

export LANGSMITH_API_KEY="<LANGSMITH_API_KEY>"

或者，可以选择一个 LangSmith SDK 配置文件，而不是导出密钥：

export LANGSMITH_PROFILE=prod

快速开始

将 Harbor 作业作为实验记录到 LangSmith：

harbor run -d "terminal-bench@2.0" \
  --agent <agent> \
  --model <provider:model> \
  --plugin langsmith

将 <agent> 替换为 Harbor Agent，并将 <provider:model> 替换为 provider:model 格式的模型。该模型必须能由已安装的 langchain-* 提供商解析，例如 anthropic:claude-opus-4-8。运行 harbor run --help 查看可用的 Agent，或参阅 Deep Agents 了解完整的 langgraph 运行示例。打开数据集与实验，选择 Harbor 同步的数据集，例如 terminal-bench@2.0，然后打开“实验”选项卡查看运行结果。

LangSmith 评估

LangSmith 插件会将每个 Harbor 作业记录到 LangSmith，因此你可以在“数据集与实验”中查看和比较结果。该插件适用于任何 Harbor Agent，而不仅仅是 Deep Agents。使用 --plugin langsmith 启用插件。快速开始展示了基本调用方式，本节将介绍插件记录的内容以及配置方法。选择一个会跟踪到 LangSmith 的 Agent，以便在实验旁边捕获完整的 Agent 跟踪记录。如果 Agent 不会跟踪到 LangSmith，插件仍会创建包含结果和反馈的数据集及实验，但不会创建 Agent 跟踪记录。如果需要消除歧义，请传入完整的导入路径，而不是简短的插件名称：

harbor run ... --plugin harbor_langsmith:LangSmithPlugin

插件要求设置 LANGSMITH_API_KEY。

查看插件记录的内容

作业运行期间，插件会通过 API 将以下信息写入 LangSmith：

数据集：从作业同步一个参考数据集。默认名称来自数据集或任务，例如 terminal-bench@2.0。每个任务都会成为一个示例，其输入包括任务名称、指令和任务 ID。
实验：每个作业创建一个实验，名称为 <name>-<job-id-prefix>，并关联到参考数据集。
运行：每次试验创建一个根运行记录，其中包含任务名称、指令、Agent 和模型的输入，并为环境、Agent 和验证阶段创建子运行记录。
反馈：针对每个验证器奖励键附加一个反馈分数，例如 reward；如果试验引发异常，还会附加 harbor_error 反馈。
输出：在每次试验运行记录中，将令牌数量记录在 tokens（input、cache、output）下，并将运行成本记录在 cost_usd 下。

在 LangSmith 中查看结果

在 LangSmith 中打开数据集与实验，选择插件同步的数据集，例如 terminal-bench@2.0，然后打开“实验”选项卡。每个 Harbor 作业都会显示为一个实验。你可以根据 reward 和 harbor_error 反馈、每次运行记录的令牌数量和成本，以及延迟来比较实验。

配置插件输入

插件会先从构造函数关键字参数中读取每个输入，如果没有，则回退到环境变量。使用环境变量设置这些输入：

HARBOR_LANGSMITH_DATASET：数据集名称。默认为根据作业生成的名称。
HARBOR_LANGSMITH_EXPERIMENT：实验基础名称。默认为作业名称。
LANGSMITH_ENDPOINT：LangSmith API 端点。默认为 https://api.smith.langchain.com。
LANGSMITH_WORKSPACE_ID：目标工作区。
HARBOR_LANGSMITH_SYNC_DATASET：设置为 false 以禁用数据集和示例同步。
HARBOR_LANGSMITH_FAIL_FAST：设置为 true，使 LangSmith API 错误直接引发异常，而不是继续运行作业。

也可以在命令行中使用 --pk，或在作业配置文件的 kwargs: 下，将相同的输入设置为插件 kwargs。这些 kwargs 与构造函数选项对应：dataset_name、experiment_name、endpoint、api_key、workspace_id、sync_dataset 和 fail_fast。

Deep Agents

langgraph Agent 会将 LangGraph 应用（例如 Deep Agent）作为 Harbor Agent 运行。使用 --agent langgraph 选择它。Harbor 会将项目放入沙箱、安装其依赖项，并在每次试验的容器中运行该图。设置 LangSmith 和模型凭据，然后运行 Harbor。harbor run 是 harbor job start 的别名，它会创建作业、启动环境并运行 LangGraph Agent：

export LANGSMITH_PROFILE=prod
export LANGSMITH_TRACING=true
export LANGSMITH_PROJECT=harbor-deepagents
export FIREWORKS_API_KEY="<FIREWORKS_API_KEY>"

harbor run \
  -t hello-world/hello-world \
  --agent langgraph \
  --model fireworks:accounts/fireworks/models/glm-5p2 \
  --ak project_path=./deep-agent \
  --ak graph=deep_agent

选择评估目标

一个任务对应一个具有固定布局的目录：task.toml 用于配置，instruction.md 用于提示词，environment/ 包含构建沙箱所需的 Dockerfile，tests/ 包含用于写入奖励的验证器。一个数据集则包含多个这样的任务目录。任务或数据集可以是本地的，也可以是远程的：你可以让 Harbor 指向自己的任务目录文件夹，也可以从 Harbor 注册表中拉取任务或数据集。以下三个输入用于选择作业运行的任务：

-t org/name[@ref]：注册表中的单个任务。远程任务会通过注册表查询获取，然后以固定提交版本克隆到 ~/.cache/harbor/tasks。
-d name@version：完整的基准测试数据集，其中包含许多任务。每个任务都会从注册表解析并克隆到缓存目录。
-p <dir>：指向单个任务或多个任务根目录的本地路径。本地路径会直接读取，不会下载，也不会复制到缓存目录。

使用 -i 和 -x（glob 包含和排除）过滤选定的任务，并使用 -l 限制任务数量。任务目录的布局如下：

hello-world/
├── task.toml         # timeouts, CPU, and memory
├── instruction.md    # the prompt given to the agent
├── environment/
│   └── Dockerfile    # image the sandbox is built from
├── tests/
│   ├── test.sh       # writes the reward to /logs/verifier/reward.txt
│   └── test_state.py # the assertions
└── solution/         # optional, used only by the oracle agent

terminal-bench/
├── hello-world/      # each subdirectory is a full task
├── fix-bug/          # (task.toml + instruction.md + environment/ + tests/)
└── parse-csv/

配置 Agent

使用 --ak 传入 Agent kwargs：

--agent langgraph：选择 LangGraph Agent。
--model <provider:model>：要运行的模型。没有默认值，因此必须提供此参数。Agent 使用 init_chat_model 解析该模型，因此模型必须采用 provider:model 格式，并且能够由已安装的 langchain-* 提供商解析，例如 anthropic:claude-opus-4-8。provider/model 格式的值会被规范化为 provider:model。模型来自 configurable['model'] 或 HARBOR_MODEL 环境变量；如果缺少模型或无法解析模型，则会引发 ValueError。
--ak project_path=<dir>：包含 langgraph.json 的本地目录。
--ak graph=<name>：要运行的 langgraph.json 中的图。
--ak config=<file>：project_path 中声明各个图的配置文件名。默认为 langgraph.json。
--ak configurable='{...}'：每次 LangGraph 运行的配置，会传入 config["configurable"]，并在调用时由图读取。常见的键包括 model、model_kwargs 和 cwd。
--ak model_kwargs='{...}'：configurable 中嵌套 model_kwargs 键的简写，例如 {"temperature": 0, "max_tokens": 8000}。
--ak dependency_overrides='[...]'：Agent 虚拟环境所需的 Pip 包。此列表会替换 langgraph.json 中声明的依赖项，因此无需编辑项目即可固定或替换版本，例如 '["deepagents==0.1.5"]'。

将 langgraph.json 指向 Agent 和依赖项

Agent 会从 project_path 中的 langgraph.json 文件加载图。该文件声明图的入口点，以及 Harbor 要在沙箱虚拟环境中安装的 Pip 依赖项：

{
  "dependencies": [
    "deepagents>=0.6.10,<0.7.0",
    "langchain-anthropic>=1.4.6,<1.5.0",
    "langchain-openai>=1.3.0,<1.4.0"
  ],
  "graphs": {
    "deep_agent": "./agent.py:make_graph",
    "research_agent": "./agent.py:make_research_graph"
  }
}

该项目公开了两个图，通过 --ak graph 选择。两者都使用 create_deep_agent 构建 Deep Agent，区别仅在于输入不同：

deep_agent：解析为 make_graph，这是一个仅使用模型创建的 Deep Agent。
research_agent：解析为 make_research_graph，这是带有研究系统提示词的同一个 Deep Agent。

每个图都会将 --model 传入的模型（从 configurable.model 读取）传给 create_deep_agent，后者使用 init_chat_model() 解析该模型：

from deepagents import create_deep_agent


def make_graph(config):
    return create_deep_agent(model=config["configurable"]["model"])


def make_research_graph(config):
    return create_deep_agent(
        model=config["configurable"]["model"],
        system_prompt="你是一名研究助理。",
    )

读取 configurable.model 的工厂函数可以让图与具体模型无关，但如果图始终应��行同一个模型，也可以直接在图中写死模型。对于固定模型，请将 langgraph.json 指向已编译的图，而不是工厂函数：

from deepagents import create_deep_agent

graph = create_deep_agent(model="fireworks:accounts/fireworks/models/glm-5p2")

在沙箱中运行 Agent

Harbor 会在每次试验的容器中运行完整的 Agent。

Single-trial lifecycle

解析并准备：harbor run 将标志解析为作业配置。作业工厂会解析并缓存任务、验证环境资源限制，并在运行任何试验前解析指标。缓存仅适用于远程任务，因此使用 -p 指定的本地任务会直接读取。
分发：Harbor 根据 n_attempts × tasks × agents 构建试验列表，然后在 -n 限制内并发运行试验，并使用 -r 进行重试。并行粒度是单次试验，因此不同任务、Agent 和尝试可以同时运行，每次试验都在独立的沙箱中执行。
创建试验：试验加载缓存的任务，根据 project_path、graph 和 model 构建 LangGraph Agent，并创建环境但不启动环境。
启动环境：环境启动并创建容器。对于 Docker 环境，此步骤会构建或复用镜像，然后运行容器。
安装 Agent：Harbor 在容器中创建虚拟环境，上传 project_path，并在容器内使用 pip 安装 langgraph.json 中的依赖项。
运行并验证：Harbor 通过 LangGraph runner 在容器内运行图，然后运行 tests/test.sh，将奖励写入 /logs/verifier/reward.txt。
完成：Harbor 停止并删除容器，写入试验结果。作业会将所有试验结果汇总为一个作业结果。

有关构建 Deep Agents 的更多信息，请参阅 Deep Agents 文档。

沙箱

langsmith Harbor 环境会在 LangSmith 沙箱中运行每次试验。使用 --env langsmith 选择该环境，即可在 LangSmith 基础设施上运行 Harbor 作业，并与其他沙箱提供商并列使用。每次试验都会获得一个独立的沙箱，Harbor 会在试验结束时将其删除。

运行评估

使用 --env langsmith 选择 LangSmith 环境并运行 Harbor 作业：

harbor run -d "<org/name>" \
  --model "<model>" \
  --agent "<agent>" \
  --env langsmith \
  -n "<n-parallel-trials>"

Harbor 会为每次试验创建一个 LangSmith 沙箱，并在其中运行 Agent 和验证器。

配置沙箱环境

LangSmith 环境会从文件系统快照启动每个沙箱。在 Harbor 任务中提供以下任一项：

预构建镜像：在 task.toml 中设置 [environment].docker_image。Harbor 会从该镜像复用或创建快照。
现有快照：传入 environment.kwargs.snapshot_name，从你已创建的快照启动。
Dockerfile：包含一个 environment/Dockerfile。Harbor 会使用任务的 environment/ 目录作为构建上下文，通过从 Dockerfile 构建流程从该文件构建快照。

使用环境 kwargs 调整沙箱生命周期，并通过 --ek 在命令行中传入：

harbor run -d "<org/name>" \
  --model "<model>" \
  --agent "<agent>" \
  --env langsmith \
  -n "<n-parallel-trials>" \
  --ek idle_ttl_seconds=0 \
  --ek delete_after_stop_seconds=7200

idle_ttl_seconds：沙箱空闲达到指定秒数后停止。设置为 0 可禁用空闲超时。
delete_after_stop_seconds：停止后的沙箱在指定秒数后删除。

故障排除

作业因身份验证错误而无法启动：确认已设置 LANGSMITH_API_KEY，或 LANGSMITH_PROFILE 指向已配置的配置文件。
Agent 因模型问题引发 ValueError：使用 provider:model 格式传入 --model，并安装匹配的 langchain-* 提供商包，以便 init_chat_model() 能够解析该模型。

另请参阅

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Evaluator types

Frameworks & integrations

Improve evaluators

前置条件

安装

身份验证

快速开始

LangSmith 评估

查看插件记录的内容

在 LangSmith 中查看结果

配置插件输入

Deep Agents

选择评估目标

配置 Agent

将 langgraph.json 指向 Agent 和依赖项

在沙箱中运行 Agent

沙箱

运行评估

配置沙箱环境

故障排除

另请参阅

​前置条件

​安装

​身份验证

​快速开始

​LangSmith 评估

​查看插件记录的内容

​在 LangSmith 中查看结果

​配置插件输入

​Deep Agents

​选择评估目标

​配置 Agent

​将 langgraph.json 指向 Agent 和依赖项

​在沙箱中运行 Agent

​沙箱

​运行评估

​配置沙箱环境

​故障排除

​另请参阅

前置条件

安装

身份验证

快速开始

LangSmith 评估

查看插件记录的内容

在 LangSmith 中查看结果

配置插件输入

Deep Agents

选择评估目标

配置 Agent

将 langgraph.json 指向 Agent 和依赖项

在沙箱中运行 Agent

沙箱

运行评估

配置沙箱环境

故障排除

另请参阅