Skip to main content
skill CX Codex

connect-agent — Claude Code skill: setup and installation

This Claude Code skill connects agent code to a running Evolving Infra stack. It attaches request identities and closes branches when their work ends.

Apache-2.0 ★ 173 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add mit-han-lab/EvolvingInfra --skill connect-agent -a claude-code
Open on GitHub

What connect-agent does

The skill links an agent’s model requests to Evolving Infra identities and closes each branch when it finishes. It locates model calls, task and sub-agent boundaries, then adds an x-agent-context header with agent_id, subagent_id, and request_id. Python projects can use the client SDK; other clients need the header on every request.

Requests can use the plain router route or the prepared path through the frontend. The skill also adds branch cleanup and checks the connection with a short task that starts a sub-agent. A running stack is required, along with its stack.json values for the router and tokenizer URLs, config_id, and retention. It does not edit the server code; changes to the agent’s code require the owner’s approval. Use deploy-stack to start the stack.

What it helps with

  • attach agent, branch, and request identities to model calls
  • represent each sub-agent as its own task branch
  • close a branch after a sub-agent returns or a task ends
  • test whether agent requests reach Evolving Infra and return a response

Example prompts for the agent

  • Connect my agent code to the running Evolving Infra stack and attach identities to model requests.
  • Set up sub-agents as separate branches and close each branch when it returns.
  • Find why Evolving Infra rejects my agent’s requests and test the connection.

How to install connect-agent

1Skills CLI (Vercel)

npx skills add mit-han-lab/EvolvingInfra --skill connect-agent -a claude-code

2Manually: put the files in place

~/.claude/skills/connect-agent/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/connect-agent/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about connect-agent

How do I install connect-agent in Claude Code?

Run npx skills add mit-han-lab/EvolvingInfra --skill connect-agent -a claude-code. The skill is placed at ~/.claude/skills/connect-agent/SKILL.md.

What does connect-agent do?

It adds agent and branch identities to requests sent to Evolving Infra, then closes branches when their work ends. It also tests the connection with a sample task.

What does connect-agent need to run?

The Evolving Infra stack must already be running. Its stack.json needs router_url, tokenizer_url, config_id, and retention; the agent’s code and the stack’s --planner setting are also needed.

Source text

SKILL.md · Apache-2.0
---
name: connect-agent
description: Connect an agent or agent framework to a running Evolving Infra stack, so that every model request carries its agent identity and every branch is ended when it finishes. Use when asked to point an agent, a sub-agent framework or OpenAI-client code at Evolving Infra, or when its requests are refused or its prefix hits stay low. Not for starting the stack; use `deploy-stack`.
---

# Connect an agent

Make an agent's model requests carry the identity that Evolving Infra uses to keep the KV of
live branches, and end each branch when it finishes. Needs a running stack
([`deploy-stack`](../deploy-stack/SKILL.md)).

## Scope

- **Reads**: `docs/api-reference.md`, `docs/kv-retention.md`, `evolving_infra/router/client/`:
  the identity header, the prepared path, ending a branch, and the Python client.
- **Writes**: nothing in this repository.
- **Never changes**: `evolving_infra/`: connecting a client needs no change to the server. If
  it seems to, stop and say why.
- **Outside the repository**: edits the agent's code, which belongs to the person. Confirm the
  change with the owner before making it.

## Inputs

- The stack's `stack.json`, in the work directory of `evolving-infra serve` on the first host:
  `router_url`, `tokenizer_url` (the frontend), `config_id` and `retention`.
- Whether the stack serves with `--planner`.
- The agent's code. Ask where it is; do not guess which repository or file sends the requests.

## Steps

### 1. Find the requests and the branches

In the agent's code, find:

- every call that sends a model request;
- where a task starts: one task run is one `agent_id`;
- where a sub-agent starts and where it returns: each sub-agent is one branch, one
  `subagent_id`;
- where the task ends.

**Check**: every model request of the agent goes through the calls found; no other HTTP
client sends model requests.

### 2. Give every request its identity

Each request carries `x-agent-context: {"agent_id": ..., "subagent_id": ..., "request_id": ...}`
([API reference](../../docs/api-reference.md#generation)):

| Field | Value |
|---|---|
| `agent_id` | one per task run, 1 to 512 bytes; two runs never share one (a new UUID per run) |
| `subagent_id` | `0` for the main branch; a new number, unique within the task, for each sub-agent |
| `request_id` | the request's position in its branch: `0`, `1`, `2`, ... |

In Python, the client SDK allocates the three numbers: `Agent(scheduler)` for the task (it draws
a new `agent_id`), `agent.fork()` for a sub-agent, `agent.request(payload)` for the identity of
the next request ([client SDK](../../docs/api-reference.md#client-sdk)). `agent.submit(payload)`
also sends it, on the plain path (`/v1/completions` or `/v1/chat/completions`). With another
client, send the header on each request:

```python
client = openai.OpenAI(base_url="<router_url>/v1", api_key="EMPTY")
identity = {"agent_id": run_id, "subagent_id": branch, "request_id": step}
client.chat.completions.create(model="<served_model_name>", messages=messages, max_tokens=1024,
                               extra_headers={"x-agent-context": json.dumps(identity)})
```

On the plain path, send chat messages, or token IDs as `prompt` on `/v1/completions`: the router
tokenizes chat messages and looks the prefix up in the KV directory, but it does not tokenize a
text `prompt`, so such a request is placed without knowing which worker holds its prefix. Do not
set `rid` in the body: the router derives it from the header and refuses a different one.

**Check**: the reply's `id` is `agent_` followed by 64 hexadecimal digits: the router used the
identity. In Python it equals `RequestIdentity(agent_id, subagent_id, request_id).engine_rid`
(`evolving_infra/router/client/agent/identity.py`).

### 3. Choose the path

Both paths work with and without `--planner`, and the planner counts the requests of both.

- **Plain path** (step 2): `/v1/chat/completions` or `/v1/completions` on the router. A role
  change from decode to prefill waits for the worker's running plain requests to finish.
- **Prepared path**: `POST <tokenizer_url>/prepare` with
  `"request_id": request.identity.engine_rid` and the stack's `config_id`, then
  `scheduler.submit_prepared(tokenizer_url, prepared, identity=request.identity)`, or
  `stream_prepared` with `"stream": true`, as in the
  [client SDK](../../docs/api-reference.md#client-sdk) example. The frontend tokenizes once and
  uploads the input to the workers, and a role change moves a running decode to another worker
  instead of waiting for it.

**Check**: a request returns generated text. On the prepared path its `meta_info.id` starts with
`agent_` (that path returns the engine's native reply); on the plain path the reply's `id` does.

### 4. End each branch

When a branch finishes (a sub-agent returns, or the task ends), end it:
`await agent.end_trajectory()` in Python (each `fork()` separately, before the `Scheduler` closes), or

```bash
curl -X POST <router_url>/kv_sessions/end -H 'Content-Type: application/json' \
  -d '{"agent_id": "<agent_id>", "subagent_id": <subagent_id>}'
```

Ending is idempotent: retry it when the call fails; sibling branches are not affected. End only a
branch that sent at least one request with its identity: the router refuses any other
(`unknown KV session`). After the end, that identity cannot send again. A router without KV
retention (`"retention": false` in `stack.json`) refuses every end (`KV session retention is
disabled`): then leave it out ([KV retention](../../docs/kv-retention.md)).

**Check**: the reply holds `"accepted": true`.

### 5. Run a task with two turns and a sub-agent

Run one short task in which the main branch sends at least two requests and starts one
sub-agent. Make the first prompt longer than a few KV pages: `#cached-token` counts whole pages
(`page_size` tokens: 64 in the GB300 configs, 256 for DeepSeek-V4-Flash).

**Check**: every reply carries an `agent_` ID (step 2 or 3); each branch's end is accepted; and
the log of the P worker that ran the second request of the main branch,
`<work dir>/logs/engine-w<i>.log` on the host of worker `w<i>`, shows its prefill batch with
`#cached-token` greater than 0.

## Returns

- The change to the agent's code: where the identity is set, where sub-agents fork, where
  branches end, and whether requests use the prepared path.
- The evidence of step 5: one reply ID, the end replies, and the `#cached-token` line.
- What the change does not cover (streaming, retries, a second client), as decisions for the
  owner.

## Pitfalls

- A prepared request sent without `identity=` runs, but its branch is not registered for KV
  retention: pass the request's identity to `submit_prepared` and `stream_prepared`.
- Two task runs that share an `agent_id` collide. On the prepared path, or with KV retention on,
  the second run's requests are refused (`request already planned; do not repeat generation`,
  `stale trajectory request`, or `trajectory has ended; use a new agent/subagent identity`); on
  the plain path without retention they run under the first run's request IDs. Make a new one
  per run.
- A closed stream does not prove that the engine stopped. With the client SDK, cancel the task
  that runs `submit_prepared`, or close the `stream_prepared` iterator: either sends
  `POST /symmetric_pd/cancel`, and the router asks both legs' engines to abort.

© mit-han-lab · Apache-2.0 · mit-han-lab/EvolvingInfra

Similar skills

SKILL.md skills catalog →

From the same set7

Project sponsors

Companies that keep this analytics open