跳到导航
Agents

Agent Harnesses

Point coding-agent CLIs at a Dynamo deployment

以 Markdown 格式查看

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.

On Chat Completions and Responses requests, function tools with explicit strict: true receive schema preflight before inference. Invalid schemas now return HTTP 400 where earlier versions could accept them. Responses validates every submitted function, including namespace members and functions excluded by allowed_tools or tool_choice: "none". Omitted, null, or false strictness and omitted or null parameters retain existing behavior.

Preflight runs independently of structural-tag activation. Passing preflight does not guarantee complete OpenAI compatibility or backend enforcement. See Request Validation for object rules, size budgets, and Dynamo’s bounded local-reference support.

1

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 examples/backends/sglang/launch/agg_agent.sh
2

Configure a harness

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

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

Dynamo’s Responses adapter currently supports function tools, including functions inside namespaces, and tool_choice values of none, auto, required, or a named function. Unsupported tool or tool-choice types return HTTP 400 before inference. Unsupported tools are rejected even when tool_choice is none or auto.

Disable Codex’s hosted web search when using Dynamo. The following command overrides the top-level web_search setting for this run:

# replace -m <model> with your model
codex -m zai-org/GLM-4.7-Flash -c model_provider=dynamo \
  -c 'web_search="disabled"'

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.

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.

Agent Headers

Dynamo carries raw coding-agent HTTP headers in AgentContext.agent_headers without interpreting them. Capture includes the open x-claude-code-* and x-codex-* families alongside supported session and subagent headers. Names within those families are not hardcoded: new headers are captured without a Dynamo schema change. Header names and values can change as coding harnesses evolve. Plugin authors and trace consumers own any parsing or normalization between harnesses.

Names are lowercase. Values remain strings, including malformed JSON, percent encoding, whitespace, empty values, and repeated values in their received order. Core code only normalizes session identity and the explicit Dynamo terminal marker.

Capture requires a recognized session identity and is bounded to 64 header values, 16 KiB per value, and 32 KiB total, counting the name once per value. Sensitive-marked and non-text values are skipped. Values exceeding the limits are omitted whole; retained values are never truncated. Missing metadata means no observation was captured, not that an event did not occur. Ordinary authentication, cookie, and unrelated protocol headers are excluded. Do not place credentials in an agent metadata header; these values are exposed to plugins and request traces.

The map travels through the frontend and worker request envelope and is available through plugin SessionContext.agent_headers(). It contains HTTP headers only; request-body metadata is not captured. The default routing policy does not interpret the map. See Agent Tracing for the request-trace format and Custom Worker Selection for plugin access.

For Claude Code custom endpoints, enable gateway hints with CLAUDE_CODE_GATEWAY_HINT_HEADERS=1. Its gateway protocol defines the header semantics. Preserving observations in AgentContext does not implement transparent Anthropic request-body or header forwarding to upstream providers.

See Also