Introducing Harness Engine: portable agent runtimes for CAIPE

[sriaradhyula]

TL;DR

Harness Engine is a provider-neutral execution layer for CAIPE. It lets the same agent-facing contract run on multiple agent harnesses while keeping channels, authorization, sessions, and streaming consistent.

The first implementation supports:

• LangChain Deep Agents as the default, backward-compatible runtime
• Amazon Bedrock AgentCore
• Claude Agent SDK

Existing agents do not need to migrate: an agent without a harness marker continues to use the default runtime. New harnesses are opt-in.

Why introduce a Harness Engine?

Agent SDKs expose different models for sessions, memory, tools, sandboxes, prompts, streaming, and multi-agent delegation. Binding CAIPE directly to each SDK would push provider-specific behavior into the UI, bots, CLI, and authorization paths.

Harness Engine creates one portable control and execution contract, with explicit provider extensions where portability is not practical. This gives CAIPE:

• one agent blueprint for common capabilities;
• harness-specific configuration driven by capability descriptors;
• durable CAIPE sessions that can bind to provider-native sessions;
• detached execution, so a client disconnect does not stop the provider run;
• replayable canonical events for reconnecting clients;
• consistent routing for Web UI, Slack, Webex, CLI, and other clients;
• a path to isolated sandbox pods without coupling clients to sandbox vendors.

SpecKit design package

PR #2401 includes a complete SpecKit package so the architecture can be reviewed from requirements through executable contracts:

Artifact	What it defines
Feature specification	User stories, functional requirements, compatibility guarantees, sandbox isolation, memory, sessions, tracing, and measurable success criteria
Architecture	Harness Gateway, control and execution planes, trust boundaries, persistence, brokers, adapters, and sandbox target
Implementation plan	Delivery sequence, ownership, rollout, validation, and rollback
Tasks	Implemented work and explicitly deferred productionization
Portable abstractions	Provider-neutral interfaces for prompts, tools, thread state, memory, sessions, sandboxes, streaming, tracing, and multi-agent delegation
Compatibility matrix	Dynamic Agents baseline and per-adapter capability evidence
Versioned contracts	REST API, canonical events, harness adapter, sandbox worker, and state/memory/tracing schemas

Scope boundary

• Implemented in feat(harness-engine): add portable runtime and BFF gateway #2401: an independent Harness Engine, BFF Harness Gateway, AgentCore and Claude SDK adapters, durable CAIPE/provider sessions, detached runs, replayable events, descriptor-driven agent creation, and harness-aware chat identity.
• Backward-compatible default: missing or legacy harness markers continue through the unchanged Dynamic Agents runtime, which provides langchain-deepagents during the staged transition.
• Future work: the LangChain Deep Agents port, claim-exclusive Kubernetes sandbox workers, production brokers, full attachment/HITL parity, certification, and cutover remain explicit follow-up gates.

The rendered architecture and source diagrams immediately below are generated from the editable Excalidraw sources in the PR.

Request-routing architecture

flowchart LR
  Clients["Web UI · Slack · Webex · CLI"] --> BFF["CAIPE BFF"]
  BFF --> Gateway["Harness Gateway"]
  Gateway -->|default| DeepAgents["LangChain Deep Agents"]
  Gateway -->|selected harness| Engine["Harness Engine"]
  Engine --> Sessions["CAIPE session manager"]
  Engine --> Runs["Detached runs + event replay"]
  Engine --> Adapters["Harness adapter registry"]
  Adapters --> AgentCore["Amazon Bedrock AgentCore"]
  Adapters --> Claude["Claude Agent SDK"]

Loading

The Harness Gateway lives at the BFF boundary. It resolves the selected agent, applies the existing authorization checks, chooses the runtime, and translates the canonical stream back to the client contract. The existing default-runtime path remains intact.

Detailed Harness Engine architecture

The detailed view distinguishes implemented paths from planned or optional integrations and shows how the unchanged Dynamic Agents default remains backward compatible.

Open the editable CAIPE system architecture

High-level source graph

The source graph maps the public routes and UI through the BFF Harness Gateway into the Harness Engine service, adapters, persistence, deployment assets, contracts, and tests.

Open the editable Harness Engine source graph

Portable agent blueprint

flowchart TB
  Blueprint["Portable agent blueprint"] --> Prompt["Prompts + model policy"]
  Blueprint --> Tools["Tool bindings"]
  Blueprint --> State["Thread + memory"]
  Blueprint --> Runtime["Sandbox + streaming"]
  Blueprint --> Delegation["Delegation + limits"]
  Prompt --> Registry["Descriptor + capability registry"]
  Tools --> Registry
  State --> Registry
  Runtime --> Registry
  Delegation --> Registry
  Registry --> Adapter["Selected harness adapter"]
  Adapter --> Events["Canonical event stream"]

Loading

The descriptor registry tells the UI which fields a harness needs, which capabilities it supports, and which provider extensions are valid. The UI can therefore render a harness-aware agent form without hard-coding every provider SDK.

Portable interfaces cover:

• prompts and model selection;
• tool and MCP server bindings;
• short-term and long-term memory;
• thread persistence and provider session binding;
• sandbox policy and workspace lifecycle;
• streaming events, replay, cancellation, and tracing;
• multi-agent delegation and execution limits.

A harness may combine providers behind these interfaces—for example, a Claude Agent SDK adapter can use an AgentCore-backed memory implementation—when the selected capabilities are compatible.

Session and reconnect lifecycle

sequenceDiagram
  participant Client
  participant Gateway as Harness Gateway
  participant Engine as Harness Engine
  participant Provider as Harness provider
  Client->>Gateway: Start turn
  Gateway->>Engine: Create authorized run
  Engine-->>Gateway: Run ID + event cursor
  Engine->>Provider: Execute with persisted session
  Provider-->>Engine: Stream provider events
  Engine->>Engine: Persist canonical events
  Client--xGateway: Disconnect
  Client->>Gateway: Reconnect with cursor
  Gateway->>Engine: Replay and continue
  Engine-->>Client: Remaining events

Loading

The CAIPE session manager owns the durable client-facing session. A provider-specific session manager can be selected behind it, and the binding between CAIPE and provider session IDs is persisted. Provider execution continues independently of the HTTP connection.

User experience

Agent catalog

The catalog shows which harness backs each agent while preserving the existing agent workflow.

Harness-aware agent creation

Selecting a harness changes the form to show supported capabilities and required provider configuration.

Harness identity in chat

Chat displays both the agent name and harness identity so parallel conversations remain distinguishable.

The screenshots contain only generic sample data and intentionally omit deployment addresses, user identities, credentials, provider resource identifiers, and organization-specific configuration.

Implementation status

The draft implementation includes:

• portable harness descriptors and blueprint validation;
• AgentCore and Claude Agent SDK adapters;
• CAIPE session records, provider-session bindings, detached runs, event replay, and cancellation;
• harness-aware routing for supported CAIPE channels;
• harness-aware creation, catalog, chat labels, colors, and badges;
• CLI contract updates for harness identity, event mapping, context forwarding, and reconnect metadata.

Backward compatibility is intentional:

• missing harness metadata selects LangChain Deep Agents;
• existing agent documents require no migration;
• existing clients can continue creating and invoking agents without specifying a harness;
• new runtime selection occurs only after the existing BFF and OpenFGA authorization path;
• the current Dynamic Agents implementation is not refactored into Harness Engine.

Current boundaries

The new adapters are experimental and are not yet a claim of exact feature parity with the default runtime. Follow-up work includes:

• production Tool, Memory, Sandbox, and Delegation brokers;
• per-run sandbox pod workers, leases, cleanup, and workspace retention policy;
• complete attachment and human-in-the-loop resume support across adapters;
• provider-call takeover after an Engine process failure;
• adapter certification tests covering capabilities, failure semantics, replay, and authorization.

Centralized authorization work remains complementary and independently mergeable. Harness Gateway currently preserves the existing BFF/OpenFGA checks before dispatching a request.

Pull requests and related design

• Harness Engine and BFF gateway — cnoe-io/ai-platform-engineering#2401
• Harness-aware CLI support — cnoe-io/caipe-cli#48
• Complementary centralized authorization work — cnoe-io/ai-platform-engineering#2395
• Related sandbox architecture discussion — #1091

Feedback requested

We would especially value feedback on:

1. What should be the minimum certification bar for a new harness adapter?
2. Which broker should be productionized first: tools, memory, sandboxes, or delegation?
3. Where should the portable blueprint stop and provider extensions begin?
4. What workspace retention and cleanup policies should sandbox pods expose?
5. How should authorization be delegated when a provider invokes tools outside the CAIPE process?

Please review the draft PRs, try the harness-aware workflows, and share use cases for additional SDKs or sandbox providers.