@botbotgo/agent-harness 0.0.91 → 0.0.93

package/README.md

@@ -75,8 +75,15 @@ Boundary documents live in:
 - `docs/feature-checklist.md`
 - `docs/long-term-memory.md`
 - `docs/app-task-pattern.md`
+- `docs/model-layering.md`
 - `docs/coding-agent-guide.md`
 
+Recommended orchestration shape for long-running flows:
+
+- let callers select the host agent explicitly whenever possible
+- use `backend: deepagent` when you want high-level execution semantics with minimal application wiring
+- use `backend: langgraph` when approvals, recovery, and long-running orchestration need application-owned workflow control
+
 ## Why This Exists
 
 Most agent demos stop at execution.
@@ -111,16 +118,20 @@ Workspace layout:
 ```text
 your-workspace/
   config/
-    workspace.yaml
     agent-context.md
-    models.yaml
-    embedding-models.yaml
-    vector-stores.yaml
-    stores.yaml
-    runtime-memory.yaml
-    backends.yaml
-    tools.yaml
-    mcp.yaml
+    runtime/
+      workspace.yaml
+      runtime-memory.yaml
+    catalogs/
+      models.yaml
+      embedding-models.yaml
+      vector-stores.yaml
+      stores.yaml
+      backends.yaml
+      tools.yaml
+      mcp.yaml
+    workflows/
+      langgraph-workflows.yaml
     agents/
       direct.yaml
       orchestra.yaml
@@ -250,7 +261,7 @@ const result = await run(runtime, {
 });
 ```
 
-`agentId: "auto"` evaluates ordered routing rules in `config/workspace.yaml`, then `routing.defaultAgentId`, and only falls back to model routing when `routing.modelRouting: true`.
+`agentId: "auto"` evaluates ordered routing rules in `config/runtime/workspace.yaml`, then `routing.defaultAgentId`, and only falls back to model routing when `routing.modelRouting: true`.
 
 ### Stream Output And Events
 
@@ -355,16 +366,17 @@ Use Kubernetes-style YAML:
 
 Core workspace files:
 
-- `config/workspace.yaml`
+- `config/runtime/workspace.yaml`
 - `config/agent-context.md`
-- `config/models.yaml`
-- `config/embedding-models.yaml`
-- `config/vector-stores.yaml`
-- `config/stores.yaml`
-- `config/runtime-memory.yaml`
-- `config/backends.yaml`
-- `config/tools.yaml`
-- `config/mcp.yaml`
+- `config/catalogs/models.yaml`
+- `config/catalogs/embedding-models.yaml`
+- `config/catalogs/vector-stores.yaml`
+- `config/catalogs/stores.yaml`
+- `config/runtime/runtime-memory.yaml`
+- `config/catalogs/backends.yaml`
+- `config/catalogs/tools.yaml`
+- `config/catalogs/mcp.yaml`
+- `config/workflows/langgraph-workflows.yaml`
 - `config/agents/direct.yaml`
 - `config/agents/orchestra.yaml`
 - `resources/tools/`
@@ -375,13 +387,14 @@ Any other local module shape is not supported, and unsupported shapes are reject
 
 There are three main configuration layers:
 
-- runtime policy in `config/workspace.yaml`
-- reusable object catalogs in `config/*.yaml`
+- runtime policy in `config/runtime/workspace.yaml`
+- reusable object catalogs in `config/catalogs/*.yaml`
 - agent assembly in `config/agents/*.yaml`
 
-### Temporary LangChain v1 Notes
+### Backend Guidance
 
 At the moment, the most stable path for complex production-style runs is `backend: deepagent`.
+`backend: langgraph` now exists as an explicit adapter boundary for LangGraph-shaped runtime entry design, but it still reuses the current LangChain-style runnable path internally rather than exposing a fully custom graph DSL.
 
 Current temporary limits on the `backend: langchain-v1` path are:
 
@@ -392,9 +405,88 @@ Current temporary limits on the `backend: langchain-v1` path are:
 Practical guidance:
 
 - use `backend: deepagent` for approvals, resume, multi-agent orchestration, rich memory flows, and heavier tool chains
+- use `backend: langgraph` when you want the agent to bind to a built-in preset or an explicit LangGraph workflow resource in config
 - keep `backend: langchain-v1` for lighter direct-response or explicitly chosen V1 agent shapes while this upstream behavior settles
 
-### `config/workspace.yaml`
+Minimal Kubernetes-style LangGraph example:
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: LangGraphWorkflows
+spec:
+  - id: default
+    entryNode: planner
+    nodes:
+      - id: planner
+        kind: planner
+      - id: executor
+        kind: executor
+    edges:
+      - from: planner
+        to: executor
+```
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Agent
+metadata:
+  name: graph-entry
+spec:
+  runtime:
+    runRoot: ./.agent
+  execution:
+    backend: langgraph
+    modelRef: model/default
+    config:
+      preset: review-loop
+```
+
+Built-in LangGraph presets currently supported:
+
+- `react`
+- `prompt-chaining`
+- `routing`
+- `parallelization`
+- `plan-execute`
+- `review-loop`
+- `evaluator-optimizer`
+- `approval-gate`
+- `handoff`
+- `orchestrator-workers`
+
+The repository also checks in matching YAML workflow resources for these patterns in
+`config/workflows/langgraph-workflows.yaml`, so applications can reference them directly with
+`workflow.ref: langgraph-workflow/<pattern-id>`.
+
+For specialist-driven presets such as `routing`, `parallelization`, `handoff`, and `orchestrator-workers`, also set:
+
+```yaml
+config:
+  preset: handoff
+  specialist: researcher
+```
+
+These presets are harness-owned workflow templates built on top of the LangGraph backend. They are not LangGraph-native node kinds or edge conditions.
+
+Use an explicit workflow ref when an application wants full graph control:
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Agent
+metadata:
+  name: graph-entry
+spec:
+  runtime:
+    runRoot: ./.agent
+  execution:
+    backend: langgraph
+    modelRef: model/default
+    config:
+      workflow:
+        ref: langgraph-workflow/default
+```
+
+### `config/runtime/workspace.yaml`
 
 Use this file for workspace-wide runtime policy.
 
@@ -450,7 +542,7 @@ Use this file for shared bootstrap memory loaded at agent construction time.
 
 Keep stable project context here. Treat it as startup context, not mutable long-term memory.
 
-### `config/models.yaml`
+### `config/catalogs/models.yaml`
 
 Use named chat-model presets:
 
@@ -466,15 +558,15 @@ spec:
 
 These load as `model/default`.
 
-### `config/embedding-models.yaml`
+### `config/catalogs/embedding-models.yaml`
 
 Use named embedding-model presets for retrieval-oriented tools.
 
-### `config/vector-stores.yaml`
+### `config/catalogs/vector-stores.yaml`
 
 Use named vector-store presets referenced by retrieval tools.
 
-### `config/stores.yaml`
+### `config/catalogs/stores.yaml`
 
 Use reusable store and checkpointer presets:
 
@@ -495,13 +587,13 @@ spec:
     path: checkpoints.sqlite
 ```
 
-### `config/runtime-memory.yaml`
+### `config/runtime/runtime-memory.yaml`
 
 Use this singleton file for runtime-owned durable long-term memory defaults.
 
 Keep bootstrap context in `config/agent-context.md`. Keep resumable execution state in the checkpointer. Use `RuntimeMemory` for durable memory policy and retrieval defaults.
 
-### `config/backends.yaml`
+### `config/catalogs/backends.yaml`
 
 Use reusable DeepAgents backend presets so filesystem and `/memories/*` topology stays in YAML:
 
@@ -522,16 +614,31 @@ spec:
         kind: StoreBackend
 ```
 
-### `config/tools.yaml`
+### `config/catalogs/tools.yaml`
 
 Use this file for reusable tool objects.
 
 Built-in tool families include function tools, backend tools, MCP tools, bundles, and provider-native tools. Provider-native tools are declared in YAML and resolved directly to upstream factories.
 
-### `config/mcp.yaml`
+### `config/catalogs/mcp.yaml`
 
 Use this file for named MCP server presets.
 
+Example:
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: McpServers
+spec:
+  - name: browser
+    transport: stdio
+    command: node
+    args:
+      - ./mcp-browser-server.mjs
+```
+
+`spec[].kind` can be omitted here; catalog entries default to `McpServer`.
+
 ### `config/agents/*.yaml`
 
 Agents always use `kind: Agent` plus `spec.execution.backend`.

package/README.zh.md

@@ -75,8 +75,15 @@
 - `docs/feature-checklist.md`
 - `docs/long-term-memory.md`
 - `docs/app-task-pattern.md`
+- `docs/model-layering.md`
 - `docs/coding-agent-guide.md`
 
+长链路编排的推荐形态：
+
+- 尽量由调用方显式指定要运行的 host agent
+- 想用高层执行语义、少写应用编排时，优先选择 `backend: deepagent`
+- 当 approvals、recovery 与长链路 orchestration 需要由应用自己控制时，使用 `backend: langgraph`
+
 ## 为何需要它
 
 多数 agent 演示停在「能跑」。
@@ -111,15 +118,20 @@ npm install @botbotgo/agent-harness
 ```text
 your-workspace/
   config/
-    workspace.yaml
     agent-context.md
-    models.yaml
-    embedding-models.yaml
-    vector-stores.yaml
-    stores.yaml
-    backends.yaml
-    tools.yaml
-    mcp.yaml
+    runtime/
+      workspace.yaml
+      runtime-memory.yaml
+    catalogs/
+      models.yaml
+      embedding-models.yaml
+      vector-stores.yaml
+      stores.yaml
+      backends.yaml
+      tools.yaml
+      mcp.yaml
+    workflows/
+      langgraph-workflows.yaml
     agents/
       direct.yaml
       orchestra.yaml
@@ -249,7 +261,7 @@ const result = await run(runtime, {
 });
 ```
 
-`agentId: "auto"` 会按顺序评估 `config/workspace.yaml` 中的路由规则，再使用 `routing.defaultAgentId`，且仅当 `routing.modelRouting: true` 时才回退到模型路由。
+`agentId: "auto"` 会按顺序评估 `config/runtime/workspace.yaml` 中的路由规则，再使用 `routing.defaultAgentId`，且仅当 `routing.modelRouting: true` 时才回退到模型路由。
 
 ### 流式输出与事件
 
@@ -354,15 +366,17 @@ await stop(runtime);
 
 核心工作区文件：
 
-- `config/workspace.yaml`
+- `config/runtime/workspace.yaml`
 - `config/agent-context.md`
-- `config/models.yaml`
-- `config/embedding-models.yaml`
-- `config/vector-stores.yaml`
-- `config/stores.yaml`
-- `config/backends.yaml`
-- `config/tools.yaml`
-- `config/mcp.yaml`
+- `config/catalogs/models.yaml`
+- `config/catalogs/embedding-models.yaml`
+- `config/catalogs/vector-stores.yaml`
+- `config/catalogs/stores.yaml`
+- `config/runtime/runtime-memory.yaml`
+- `config/catalogs/backends.yaml`
+- `config/catalogs/tools.yaml`
+- `config/catalogs/mcp.yaml`
+- `config/workflows/langgraph-workflows.yaml`
 - `config/agents/direct.yaml`
 - `config/agents/orchestra.yaml`
 - `resources/tools/`
@@ -373,13 +387,14 @@ await stop(runtime);
 
 主要有三层配置：
 
-- `config/workspace.yaml` 中的运行时策略
-- `config/*.yaml` 中的可复用对象目录
+- `config/runtime/workspace.yaml` 中的运行时策略
+- `config/catalogs/*.yaml` 中的可复用对象目录
 - `config/agents/*.yaml` 中的 agent 装配
 
-### LangChain v1 的暂时说明
+### Backend 选择建议
 
 当前对于复杂、生产化风格的运行链路，最稳定的路径仍然是 `backend: deepagent`。
+现在也支持 `backend: langgraph` 作为显式的 LangGraph 风格 adapter 边界；不过内部实现当前仍复用现有 LangChain runnable 路径，还不是完整自定义 graph DSL。
 
 目前 `backend: langchain-v1` 这条路径的暂时限制是：
 
@@ -390,9 +405,44 @@ await stop(runtime);
 实际建议：
 
 - approvals、resume、多 agent orchestration、复杂 memory 流、重工具链，优先使用 `backend: deepagent`
+- 如果你想让 agent 在配置层显式绑定到一个 LangGraph workflow 资源，使用 `backend: langgraph`
 - `backend: langchain-v1` 先保留给轻量 direct-response 场景，或明确需要 V1 agent 语义的工作区
 
-### `config/workspace.yaml`
+最小的 Kubernetes 风格 LangGraph 示例：
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: LangGraphWorkflows
+spec:
+  - id: default
+    entryNode: planner
+    nodes:
+      - id: planner
+        kind: planner
+      - id: executor
+        kind: executor
+    edges:
+      - from: planner
+        to: executor
+```
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Agent
+metadata:
+  name: graph-entry
+spec:
+  runtime:
+    runRoot: ./.agent
+  execution:
+    backend: langgraph
+    modelRef: model/default
+    config:
+      workflow:
+        ref: langgraph-workflow/default
+```
+
+### `config/runtime/workspace.yaml`
 
 用于工作区范围的运行时策略。
 
@@ -448,7 +498,7 @@ spec:
 
 在此放置稳定的项目上下文；视为启动上下文，而非可变长期记忆。
 
-### `config/models.yaml`
+### `config/catalogs/models.yaml`
 
 命名聊天模型预设：
 
@@ -464,15 +514,15 @@ spec:
 
 加载为 `model/default`。
 
-### `config/embedding-models.yaml`
+### `config/catalogs/embedding-models.yaml`
 
 面向检索类工具的命名嵌入模型预设。
 
-### `config/vector-stores.yaml`
+### `config/catalogs/vector-stores.yaml`
 
 检索工具引用的命名向量库预设。
 
-### `config/stores.yaml`
+### `config/catalogs/stores.yaml`
 
 可复用的存储与 checkpointer 预设：
 
@@ -493,7 +543,7 @@ spec:
     path: checkpoints.sqlite
 ```
 
-### `config/backends.yaml`
+### `config/catalogs/backends.yaml`
 
 可复用的 DeepAgents 后端预设，使文件系统与 `/memories/*` 拓扑保留在 YAML 中：
 
@@ -514,16 +564,31 @@ spec:
         kind: StoreBackend
 ```
 
-### `config/tools.yaml`
+### `config/catalogs/tools.yaml`
 
 可复用工具对象。
 
 内置工具族包括函数工具、后端工具、MCP 工具、bundle 与原生 provider 工具。原生 provider 工具在 YAML 中声明并直接解析到上游工厂。
 
-### `config/mcp.yaml`
+### `config/catalogs/mcp.yaml`
 
 命名 MCP 服务预设。
 
+示例：
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: McpServers
+spec:
+  - name: browser
+    transport: stdio
+    command: node
+    args:
+      - ./mcp-browser-server.mjs
+```
+
+这里可以省略 `spec[].kind`；catalog 项会默认按 `McpServer` 处理。
+
 ### `config/agents/*.yaml`
 
 Agent 始终使用 `kind: Agent` 以及 `spec.execution.backend`。

package/dist/benchmark/upstream-runtime-ab-benchmark.d.ts

@@ -1,4 +1,4 @@
-export declare const DEFAULT_UPSTREAM_BENCHMARK_PATHS: readonly ["harness", "raw-langchain-v1", "raw-deepagent"];
+export declare const DEFAULT_UPSTREAM_BENCHMARK_PATHS: readonly ["harness", "raw-langchain-v1", "raw-langgraph", "raw-deepagent"];
 export declare const DEFAULT_UPSTREAM_BENCHMARK_WORKLOAD: "tool";
 export type UpstreamBenchmarkPath = (typeof DEFAULT_UPSTREAM_BENCHMARK_PATHS)[number];
 export type UpstreamBenchmarkWorkload = "tool" | "no-tool";

package/dist/benchmark/upstream-runtime-ab-benchmark.js

@@ -1,6 +1,7 @@
 export const DEFAULT_UPSTREAM_BENCHMARK_PATHS = Object.freeze([
     "harness",
     "raw-langchain-v1",
+    "raw-langgraph",
     "raw-deepagent",
 ]);
 export const DEFAULT_UPSTREAM_BENCHMARK_WORKLOAD = "tool";
@@ -47,7 +48,7 @@ export function resolveUpstreamBenchmarkPaths(rawValue) {
     const parsed = rawValue
         .split(",")
         .map((value) => value.trim().toLowerCase())
-        .filter((value) => value === "harness" || value === "raw-langchain-v1" || value === "raw-deepagent");
+        .filter((value) => value === "harness" || value === "raw-langchain-v1" || value === "raw-langgraph" || value === "raw-deepagent");
     return parsed.length > 0 ? parsed : [...DEFAULT_UPSTREAM_BENCHMARK_PATHS];
 }
 export function resolveUpstreamBenchmarkWorkload(rawValue) {