> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://docs.nvidia.com/dynamo/llms.txt. For full content including API reference and SDK examples, see https://docs.nvidia.com/dynamo/llms-full.txt.

# Agent Harnesses

Dynamo exposes `v1/chat/completions`, `v1/responses`, and `v1/messages`, so any agent that uses these APIs can talk to a Dynamo endpoint even if it is not listed in this guide. This guide focuses on popular agent harnesses that send stable session IDs. Dynamo normalizes these IDs for tracing and other explicitly configured consumers.

#### Start a local agent endpoint

To locally test these out, we have a small script that runs an SGLang-backed `zai-org/GLM-4.7-Flash` endpoint. This script starts a TP2 instance on port 8000 and enables request tracing for replay and visualization. By default traces are saved in `/tmp/dynamo-request-trace-$(date +%Y%m%d-%H%M%S)`

To start it, run:

```bash
bash examples/backends/sglang/launch/agg_agent.sh
```

#### Configure a harness

#### Codex

Codex uses the Responses API. Add a local provider in `~/.codex/config.toml`:

```toml
[model_providers.dynamo]
name = "dynamo"
base_url = "http://localhost:8000/v1"
wire_api = "responses"
```

```bash
# replace -m <model> with your model
codex -m zai-org/GLM-4.7-Flash -c model_provider=dynamo
```

Dynamo maps Codex's `thread-id` header to `session_id`. A spawned child thread also sends `x-codex-parent-thread-id`, which Dynamo maps to `parent_session_id`.

#### Pi

Pi uses the Dynamo provider plugin. Build and install it from the [agent-plugins](https://github.com/ai-dynamo/agent-plugins/tree/main/pi-plugin) checkout:

```bash
git clone https://github.com/ai-dynamo/agent-plugins.git ~/agent-plugins
cd ~/agent-plugins/pi-plugin
npm install && npm run build
pi install "$PWD"
```

Point it at the Dynamo OpenAI-compatible endpoint and run Pi with the `dynamo` provider:

```bash
export DYNAMO_BASE_URL=http://localhost:8000/v1
export DYNAMO_API_KEY=dynamo-local

pi --model dynamo/zai-org/GLM-4.7-Flash
```

#### Claude Code

Claude Code uses the Anthropic-compatible Messages API. The local launcher above starts `dynamo.frontend` with `--enable-anthropic-api`; for other deployments, pass that flag when starting the frontend. Then set:

```bash
export ANTHROPIC_BASE_URL=http://localhost:8000
export ANTHROPIC_MODEL=zai-org/GLM-4.7-Flash
export ANTHROPIC_SMALL_FAST_MODEL=zai-org/GLM-4.7-Flash
export CLAUDE_CODE_ATTRIBUTION_HEADER=0 # preserve KV cache hits
export ANTHROPIC_API_KEY=

claude
```

Dynamo uses `x-claude-code-session-id` as the Claude Code session ID. For subagents, Dynamo uses `x-claude-code-agent-id` as the child session ID. Nested subagents use `x-claude-code-parent-agent-id` as the parent; top-level subagents fall back to the root session ID.

#### OpenCode

OpenCode uses a project-local JSONC provider config; setting an endpoint environment variable alone is not enough. Create `.opencode/opencode.jsonc` in the project where you run OpenCode:

```jsonc
{
  "provider": {
    "dynamo": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Dynamo",
      "models": {
        "zai-org/GLM-4.7-Flash": {
          "id": "zai-org/GLM-4.7-Flash",
          "name": "GLM 4.7 Flash"
        }
      },
      "options": {
        "baseURL": "http://localhost:8000/v1"
      }
    }
  },
  "permission": {
    "task": "allow"
  }
}
```

Run OpenCode with the provider/model pair:

```bash
opencode -m dynamo/zai-org/GLM-4.7-Flash
```

Dynamo maps OpenCode's `x-session-id` header to `session_id` and `x-parent-session-id` to `parent_session_id`.

#### OpenClaw

OpenClaw can use Dynamo through its OpenAI-compatible Responses endpoint. Install the Dynamo provider plugin:

```bash
git clone https://github.com/ai-dynamo/agent-plugins.git ~/agent-plugins
openclaw plugins install --link ~/agent-plugins/openclaw-plugin
openclaw plugins enable dynamo
```

Add a Dynamo-backed model to `~/.openclaw/openclaw.json`:

```jsonc
{
  "models": {
    "providers": {
      "dynamo": {
        "baseUrl": "http://localhost:8000/v1",
        "apiKey": "dynamo-local",
        "api": "openai-responses",
        "models": [
          {
            "id": "zai-org/GLM-4.7-Flash",
            "name": "Dynamo GLM 4.7 Flash",
            "reasoning": true,
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "dynamo/zai-org/GLM-4.7-Flash"
      }
    }
  }
}
```

Run OpenClaw:

```bash
openclaw chat
```

The plugin copies OpenClaw's current `sessionId` into `x-dynamo-session-id` on each request. Native subagents receive their own `session_id`, and the immediate parent is recorded as `parent_session_id`.

#### Hermes Agent

Hermes uses an OpenAI-compatible custom endpoint. Configure Hermes with the served model name and Dynamo `/v1` base URL:

```yaml
model:
  default: zai-org/GLM-4.7-Flash
  provider: custom
  base_url: http://localhost:8000/v1
  api_mode: chat_completions
```

If your Dynamo endpoint requires authentication, add `api_key: <token>` to the Hermes model config or set `OPENAI_API_KEY`.

This configuration lets you run Hermes with the `hermes` command. To send session IDs to Dynamo, install the plugin:

```bash
# clone the plugin
git clone https://github.com/ai-dynamo/agent-plugins.git ~/agent-plugins
# link it to where Hermes typically looks for plugins
ln -sfnT ~/agent-plugins/hermes-plugin ~/.hermes/plugins/dynamo_session
hermes plugins enable dynamo_session

# run Hermes
hermes
```

The plugin copies the Hermes `session_id` into `x-dynamo-session-id` on each LLM request.

## Drive a Harness from Another Agent

Use the repository's `.agents/skills/dynamo-agent-harness` skill when an agent needs to keep a Claude Code, Codex, or OpenCode session open across multiple prompts while Dynamo serves the model. The skill uses Agent Client Protocol (ACP) and injects the provider configuration through the child process environment instead of adding harness configuration files to the delegated worktree.

The skill pins the Claude Code and Codex ACP adapters. If a harness release changes the model, endpoint, session header, authentication, or mode configuration, update this page and the skill in the same change after running a persistent two-turn tool smoke test.

## Compaction Signals

An agent harness can compact older conversation history into a summary when its context approaches a limit. The harness creates the summary request and keeps the logical session ID stable. Dynamo observes supported compaction signals but does not start compaction.

| Harness     | Signal recognized by Dynamo                                     | Normalized agent context   |
| ----------- | --------------------------------------------------------------- | -------------------------- |
| Codex       | `x-codex-turn-metadata` with `request_kind` set to `compaction` | `agent_context.compaction` |
| Claude Code | No supported mapping                                            | Unset                      |
| OpenCode    | No supported mapping                                            | Unset                      |

For Codex, Dynamo preserves the optional `trigger`, `reason`, `implementation`, `phase`, and `strategy` values. The object appears only on the inference request that creates the summary. Invalid JSON and other request kinds leave it unset.

Workers receive the field in `AgentContext` but do not act on it.

Compaction metadata is passive. It does not rotate `session_id`, change request routing, or evict KV cache blocks. See [Agent Tracing](/dynamo/dev/agents/agent-tracing#compaction-metadata) for the request-trace format.

## See Also

* [Session IDs](/dynamo/dev/agents/session-i-ds)
* [Agent Tracing](/dynamo/dev/agents/agent-tracing)
* [SGLang for Agentic Workloads](/dynamo/dev/knowledge-base/modular-components/backends/sg-lang/agents-on-sg-lang)