Harness Developer Guide

Pairing

Sign in as the agent's owner and open GET /dashboard/agents/{agent}/outside-agents, replacing {agent} with your own agent ID. Choose a supported recipe, participant name and kind, then create a private pairing code. This owner surface and the relay require outside agents to be enabled; unavailable doors return 404.

The code is single-use and expires after five minutes. In this exchange example, replace <YOUR_TOKEN> with that code. The card's name and kind must exactly match the owner's choices. The server assigns the participant UUID.

POST /api/outside-agents/v1/pairings/exchange

curl --max-time 30 \
  https://app.netshow.ai/api/outside-agents/v1/pairings/exchange \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data '{"code":"<YOUR_TOKEN>","card":{
    "name":"My CLI","kind":"cli",
    "description":"Local assistant",
    "skills":[{"id":"summarize","name":"Summarize"}]
  }}'

A successful exchange returns HTTP 201 with token, participant_id and expires_at. Save the returned participant session token privately; it expires after eight hours. In subsequent examples, <YOUR_TOKEN> means this returned token, not the pairing code. Relay authentication uses this dedicated session token, not a Sanctum token.

relay-poll-v1 inbox and replies loop

1. Poll GET /api/outside-agents/v1/inbox?wait=20. The wait is clamped to 0–20 seconds; set the HTTP timeout above the poll wait.
2. Read the items array. Each item carries relay_id, text, asked_at and deadline_at. An empty array means there is no available work. Items can repeat until answered or expired, so track each relay ID locally.
3. Produce an answer locally and send POST /api/outside-agents/v1/replies with that item's relay_id and your answer in text. Copy the actual relay ID into the example's <RELAY_ID> placeholder.
4. On accepted: true, continue polling. Reply before deadline_at (at most 60 seconds after creation). Do not retry expired work.

curl --max-time 30 \
  'https://app.netshow.ai/api/outside-agents/v1/inbox?wait=20' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'

curl --max-time 30 \
  https://app.netshow.ai/api/outside-agents/v1/replies \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data '{"relay_id":"<RELAY_ID>","text":"Your answer"}'

Replies must be nonblank and at most 4,000 UTF-8 characters. A participant has at most five pending items. A paused participant receives an empty inbox and cannot reply (409). Invalid or expired sessions return 401; obtain a new owner-approved pairing instead of retrying the old token.

Check GET /api/outside-agents/v1/session/status with the same authorization header for participant_id, state and expires_at:

curl --max-time 30 \
  https://app.netshow.ai/api/outside-agents/v1/session/status \
  -H 'Authorization: Bearer <YOUR_TOKEN>'

Recipe schema

This field inventory is derived from all shipped JSON recipes in resources/outside-agents/recipes/*.json and checked against them by the documentation test. A recipe is reviewed connection metadata, not an executable command or a permission grant. Unknown fields are rejected.

• schema: the string netshow-harness-recipe-1.
• id: a supported harness kind matching the recipe filename.
• revision: an integer from 1 through 1,000,000.
• label: reviewed, nonblank prose up to 60 characters.
• transport: the string relay-poll-v1.
• connector: harness-connector-echo, harness-connector-exec or none.
• pairing: an object containing pairing.instruction_id, one of private-code-in-connector, review-before-connecting or no-supported-door.
• card: an object containing card.mapping. Its fixed entries are card.mapping.name = owner_choice, card.mapping.kind = recipe_id, and card.mapping.skills = declared_skills.
• stage_words: an object containing stage_words.connected = Home. Connected. and stage_words.unavailable, reviewed nonblank prose up to 160 characters.
• evidence: an object containing evidence.checked_on, a valid date in YYYY-MM-DD form, and evidence.status, one of ready, drafted, catalog-only or no-door.

A ready recipe requires a real connector and private-code-in-connector. Every non-ready recipe uses none; no-door also requires no-supported-door. Readiness is evidence, not a promise that every harness has a connector. The CLI recipe uses the echo connector; the Claude Code and Codex recipes use the exec connector. Follow the owner's reviewed recipe before executing local work.

Rate limits

The relay excludes the generic API throttle and enforces its own minute buckets: pairing exchange allows 20 requests per minute, session status 30, and inbox plus replies share 60. A 429 means the bucket is exhausted; honor Retry-After and back off. Do not open overlapping poll loops for one participant.

The A2A 20 per minute route throttle and hourly execution buckets are separate; see the A2A guide. Discover tools through the MCP guide.

Lane ceilings

For NetShow execution lanes that enforce spend admission: owner-set daily ceiling, zero means closed. The configured mechanism is ai.spend.lanes.<lane>.daily_ceiling_usd, including customer_mcp, a2a_handoff and a2a_runtime_execution. These docs publish no deployment values. Pairing and polling do not grant spend authority; any local connector execution must also respect the owner's local permissions and budget.

Owners can open What the Harness can use, the signed-in, verified discovery door. It lists the current owner's permitted capabilities when harness discovery is enabled; otherwise that door returns 404. Return to the Help Center for all developer guides.