使用 LangSmith 在一个地方运行、追踪、比较和计算代理评估， Harbor 作为执行层。Harbor 是一个在沙盒环境中评估和优化代理及语言模型的框架，来自 Terminal-Bench的创造者。它在隔离容器中运行每个试验，因此您可以同时并行化评估和部署到多个环境中。

LangSmith 在三个点与 Harbor 集成：

• LangSmith 评估：将每个 Harbor 作业记录到 LangSmith 作为实验， --plugin langsmith.
• Deep Agents：将 LangGraph 或 Deep Agents 应用程序作为 Harbor 代理运行， --agent langgraph.
• 沙盒环境：在 LangSmith 沙盒环境上运行每个 Harbor 试验， --env langsmith.

本页面介绍 LangSmith 特定的 Harbor 标志。要获取完整的 CLI，请运行 harbor run --help 或参阅 Harbor 文档.

先决条件

• - A LangSmith 账户 和一个 API 密钥.
• - 已安装 Python， pip.
• - 模型提供商的 API 密钥（您的代理调用的模型），例如 ANTHROPIC_API_KEY.

安装

使用 langsmith 额外组件安装 Harbor。该额外组件包含 harbor-langsmith LangSmith 插件、环境和代理使用的包：

pip install "harbor[langsmith]"

身份验证

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

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

快速开始

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

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

将 <agent> 替换为 Harbor 代理， <provider:model> 替换为 provider:model 格式，该格式可由已安装的 langchain-* 提供商解析，例如 anthropic:claude-opus-4-8。运行 harbor run --help 以列出可用的代理，或参阅 Deep Agents 获取完整的 langgraph run.

打开 数据集和实验，选择 Harbor 同步的数据集，例如 terminal-bench@2.0，然后打开实验标签页查看运行情况。

LangSmith 评估

LangSmith 插件将每个 Harbor 作业记录到 LangSmith，以便您可以在数据集和实验下查看和比较结果。该插件适用于任何 Harbor 代理，不仅限于 Deep Agents。使用以下方式启用它 --plugin langsmith。 快速开始 展示了基本调用，本节介绍插件记录的内容以及如何配置它。

选择一个可追踪到 LangSmith 的代理，以在实验旁边捕获完整的代理追踪。如果代理不追踪到 LangSmith，插件仍会创建数据集和实验以及结果和反馈，但不包含代理追踪。

需要消除歧义时，请传递完整的导入路径而不是短插件名称：

harbor run ... --plugin harbor_langsmith:LangSmithPlugin

插件需要 LANGSMITH_API_KEY.

查看插件记录的内容

作业运行时，插件通过 API 向 LangSmith 写入数据：

• 数据集：从作业同步参考数据集。默认名称来自数据集或任务，例如 terminal-bench@2.0。每个任务成为一个示例，其输入为任务名称、指令和任务 ID。
• 实验：每个作业创建一个实验，命名为 <name>-<job-id-prefix>，链接到参考数据集。
• 运行：为每个试次创建一个根运行，包含任务名称、指令、代理和模型的输入，以及环境、代理和验证阶段对应的子运行。
• 反馈：为每个验证器奖励键附加一个反馈分数，例如 reward，以及当试次引发异常时的 harbor_error 反馈。
• 输出：在 tokens (input, cache, output下记录 token 数量，并在 cost_usd 下记录每次试次运行的费用。

在 LangSmith 中查看结果

打开 LangSmith 中的数据集和实验 ，选择插件同步的数据集，例如 terminal-bench@2.0，然后打开实验标签页。每个 Harbor 作业显示为一个实验，您可以 比较实验 根据 reward 和 harbor_error 反馈、每次运行记录的 token 数量和费用，以及延迟时间。

配置插件输入

插件首先从构造函数关键字参数读取每个输入，然后回退到环境变量。使用环境变量设置输入：

• - **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.

深度代理

langgraph 代理运行一个 LangGraph 应用程序（如深度代理）作为 Harbor 代理。使用 --agent langgraph. Harbor 会将您的项目暂存到沙箱中，安装其依赖项，并在每个试验的容器内运行图。

设置您的 LangSmith 和模型凭证，然后运行 Harbor。 harbor run 是的别名 harbor job start，它会构建作业、启动环境并运行 LangGraph 代理：

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/

配置代理

使用 --ak:

• - **--agent langgraph**：选择 LangGraph 代理。
• - **--model <provider:model>**：要运行的模型。没有默认值，因此此值是必需的。代理使用 @[init_聊天_模型]，因此必须能被已安装的 langchain-* 提供商解析 provider:model 格式，例如 anthropic:claude-opus-4-8. A 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='{...}'**：传递给 config["configurable"] 的 LangGraph 每次运行配置，并在调用时由图读取。常用键为 model, model_kwargs和 cwd.
• - **--ak model_kwargs='{...}'**：嵌套 model_kwargs 键的简写 configurable，例如 {"temperature": 0, "max_tokens": 8000}.
• - **--ak dependency_overrides='[...]'**：代理虚拟环境的 Pip 包。此列表替换 langgraph.json中声明的依赖项，允许您固定或更换版本而无需编辑项目，例如 '["deepagents==0.1.5"]'.

指向代理和依赖项的 langgraph.json

代理从 langgraph.json 文件加载图 project_path。该文件声明了图的入口点以及 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) to 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="You are a research assistant.",
    )

一个读取的工厂函数 configurable.model 保持了图与模型的解耦，但你也可以在图中硬编码模型（当它应该始终运行同一个模型时）。对于固定模型，请将以下指向编译后的图 langgraph.json 而不是工厂函数：

from deepagents import create_deep_agent

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

在沙盒中运行代理

Harbor 在试验容器内运行整个代理。

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

沙盒

该 langsmith Harbor 环境在 LangSmith 沙盒上运行每个试验。选择它使用 --env langsmith 在 LangSmith 基础设施上执行 Harbor 作业，以及其他沙盒提供商。每个试验获得自己的沙盒，Harbor 在试验完成时删除该沙盒。

运行评估

运行 Harbor 任务并使用以下方式选择 LangSmith 环境 --env langsmith:

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

Harbor 为每个试验创建一个 LangSmith 沙盒，并在其中运行代理和验证器。

配置沙盒环境

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

• 预构建镜像：设置 [environment].docker_image in task.toml。Harbor 将从该镜像重复使用或创建快照。
• 现有快照：传递 environment.kwargs.snapshot_name 以从 快照 启动，你已创建该快照。
• Dockerfile：包含一个 environment/Dockerfile。Harbor 使用 从 Dockerfile 构建流程，使用任务 environment/ 目录作为构建上下文。

使用环境 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 指向已配置的配置文件。
• - **代理抛出 ValueError 模型**：传递 --model in provider:model 格式，并安装匹配的 langchain-* provider 包，以便 init_chat_model() 能够解析它。

另请参阅

• - 使用 Harbor 运行评估
• - Deep Agents 文档
• - 数据集和实验
• - 分析实验
• - 沙盒快照
• - Harbor 文档