Register an external HTTP agent

In the sidebar, click Agents → Register agent. Visible only to Org Admins and Project Admin Owners.

Form fields

Name, description

• Name (required, ≤ 255 chars).
• Description (optional, ≤ 5000 chars).

Mode

• External HTTP (default) — your agent runs in your infrastructure; Pipelines POSTs each task to your endpoint. This page.
• Sandbox Agents — Pipelines runs your code (or a coding CLI) in a platform sandbox per task. See Register a sandbox agent.

External HTTP fields

• Endpoint URL (required) — must be a publicly reachable HTTPS URL. The validator rejects localhost, the GCP metadata host, and private / loopback / link-local / reserved IPs. For local iteration, use the pipelines odyssey dev placeholder (see Local development).
• Auth header name (optional) — typically Authorization or X-API-Key.
• Auth header value (optional, write-only) — the literal secret (include Bearer if your endpoint expects it). Stored encrypted.

Network reachability

Every dispatch has two hops. The Test connection button covers inbound (platform → your endpoint). For outbound (your agent → the per-run proxy), run the outbound reachability probe from inside your agent's runtime — HTTP 401 is the success signal. Use it when the trace tab shows agent_unreachable or the completion warning banner.

Tools

Build the agent's tools_schema here. Click Import JSON to paste an entire list. The importer accepts both OpenAI function-calling shape (name / description / parameters) and our native shape (name / description / input_schema), plus the Chat Completions per-tool wrapper ({type: "function", function: {...}}).

Imported tools land in sandbox mode. Flip individual ones to passthrough via the per-tool mode chip (active only once at least one mcp_server / http_openapi / code tool endpoint exists in your org). See Tools schema.

Ledger schema (optional)

The Ledger schema editor lets you declare the typed entities your simulated world state carries, for tighter consistency and validated seeds. Optional — leave it empty for the default open ledger, or click Generate to draft one from your tools. See Ledger schema.

Multi-agent topology (optional)

If your agent is internally multi-agent (a supervisor delegating to specialists, or peers handing work back and forth), use the Topology editor — or the Multi-agent → Import JSON dialog — to declare which sub-agents exist (actor_id), what tools each owns, who they talks_to, and the entry sub-agent. The declaration is stored on agent.config as { sub_agents, topology } and grounds the reconstructed graph in the trace tab. It's optional and never gates a run. Generate the JSON straight off your code with pipelines odyssey dump-agent ... --section topology. Full flow: Multi-agent systems.

Concurrency cap

Maximum simultaneous dispatches against this agent. Default 5, range 1–100. Sandbox-mode tool calls are LLM-backed; per-call latency increases with concurrency. Start at 1–2 for local dev.

Run timeout

Maximum dispatch duration. Default 300 s, max 1800 s. Each sandbox-mode tool call takes 3–20 s. Budget 30–200 s for proxy time on a 10-call agent, plus model thinking time.

Pick simulator + judge models

After registering, when you wire the agent into a Pipeline Builder workflow, the agent-mode field's Models popover lets you pick two models independently per field:

• Odyssey simulator model — the LLM Odyssey runs to simulate sandbox-mode tool responses against your declared tools_schema.
• Judge model — the LLM that scores each completed run (pass / fail
  • failure mode + rubric breakdown).

Each picker resolves through the platform's standard model-resolution chain:

1. The picker selection on this field, if set.
2. The organization's default custom model (set on Settings → Models), if the picker is left on Use org default.
3. Otherwise the dispatch fails with agent_model_unresolved — pick a model on the field, or set an org default.

Both models charge against the org's BYOK credential (e.g. OPENROUTER_API_KEY); the platform never bills LLM cost itself for Odyssey simulator or judge calls.

Secrets you'll juggle

For wrapper code (inbound auth, ping short-circuit, the canonical ~60-line wrapper) see Porting without the SDK → Step 4 or the Agent SDK for Python.

API equivalent

The form posts to POST /api/agents. Hit it directly for IaC or scripted seeding:

{
  "name": "my-claude-agent",
  "description": "Customer-support triage agent.",
  "mode": "external_http",
  "config": {
    "endpoint_url": "https://agents.example.com/dispatch",
    "auth_header_name": "Authorization",
    "auth_credential_value": "Bearer sk-replace-with-real-token"
  },
  "tools_schema": [
    {
      "name": "get_order",
      "input_schema": {"type": "object", "properties": {"order_id": {"type": "string"}}, "required": ["order_id"]},
      "default_execution_mode": "sandbox"
    }
  ],
  "concurrency_cap": 5,
  "run_timeout_s": 300
}

For mode: "code" bodies (single-file, multi-file, git, ZIP, CLI run command) see Sandbox agent reference → API equivalent.

passthrough_binding accepts either endpoint_id (UUID) or endpoint_name (resolved at registration time, unique within your org).

ledger_schema is optional (null = open ledger). To declare one, see Ledger schema. On PUT, omit it to leave it unchanged or send null to clear it.

auth_credential_value is write-only; reads return a server-managed auth_credential_id instead. Resubmitting a config without auth_header_name clears the credential.

Editing, versioning, deletion

The detail page (/agents/{agentId}) is read-only. Edits go through PUT /api/agents/{agent_id}:

curl -X PUT https://api.pipelines.tech/api/agents/{agent_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "concurrency_cap": 10, "run_timeout_s": 600 }'

Material edits (config, tools, caps) create a new agent version. Renames and description edits do not.