register-peer-agent

Register an external agent on another platform as a peer agent connection, so that a process flow can hand a whole goal to it. It returns the connection_id that an external agent node takes as registration_id. Needs the fabric:orchestrate.write grant.

The shape of result for register-peer-agent is not recorded here: it was not captured against a live deployment. Call it once and read what comes back rather than assuming a shape.

curl -sS -X POST https://fabric.wexa.ai/mcp/$FABRIC_PROJECT_ID \
  -H "authorization: Bearer $FABRIC_API_KEY" \
  -H "Mcp-Session-Id: $MCP_SESSION_ID" \
  -H "content-type: application/json" -H "accept: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"register-peer-agent","arguments":{"name":"invoice-reconciler","endpoint":"https://agents.example.com/a2a/invoice-reconciler","protocol":"a2a","secret":"<token>"}}}'

curl -sS https://fabric.wexa.ai/v1/register-peer-agent \
  -H "authorization: Bearer $FABRIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"invoice-reconciler","endpoint":"https://agents.example.com/a2a/invoice-reconciler","protocol":"a2a","secret":"<token>"}'

import { Fabric } from '@wexa-fabric/sdk'

const fabric = new Fabric()
const result = await fabric.registerPeerAgent({
  name: 'invoice-reconciler',
  endpoint: 'https://agents.example.com/a2a/invoice-reconciler',
  protocol: 'a2a',
  secret: '<token>'
})

from wexa import Fabric

fabric = Fabric()
out = fabric.register_peer_agent(
    name="invoice-reconciler",
    endpoint="https://agents.example.com/a2a/invoice-reconciler",
    protocol="a2a",
    secret="<token>",
)

Parameters

Parameter	Type	Required	Notes
`name`	string	Required	Non-empty. Unique within this project; a duplicate is refused (502), the message says so, and nothing is created: pick a different name.
`endpoint`	string	Required	The external agent's full `http://` or `https://` URL. Non-empty.
`protocol`	string	Required	`mcp` or `a2a`: which protocol the external agent speaks. Any other value is refused, and the refusal names both.
`secret`	string	Optional	The credential. Sent as `Authorization: Bearer <secret>` on every call; no header when empty. Supplied once, here; no tool ever returns it.
`description`	string	Optional	A description of the connection.
`platform`	string	Optional	A label for which platform this agent runs on.
`auth`	string	Optional	Only `key` works today (the default). `oauth` and `mtls` are refused: they are not supported yet.

More details

Test the endpoint first with handshake-peer-agent. Registration runs its own handshake as well and records what the external agent says about itself; list-peer-agents shows it afterwards. The name is the only thing telling two connections apart anywhere a person looks, which is why it must be unique. A connection holds your credential once, and no tool returns it afterwards, in any form.

How the secret is sent. When secret is set, it goes as Authorization: Bearer <secret> on every call to the external agent. When it is empty, no header is sent. Wexa does not fetch or refresh tokens, so a short-lived token, such as a Google access token, stops working when it expires.

An MCP external agent must expose exactly one tool. Registration runs its own handshake, and when an MCP external agent exposes more tools than one, or none, that handshake fails. The connection is still recorded, but an external agent node that points at it fails when it runs. Run handshake-peer-agent first, and register only an endpoint whose handshake succeeds.

This registers the console's "single peer agent" connection type, which takes a whole goal. The console's other connection type, a tool catalog, is a different concept and is console-only.

Use it from a process flow

Put the connection_id on an interop_agent node, the external agent node, of a process flow as registration_id. The node carries no skills and no approval step: the external agent brings its own abilities and runs its step on its own platform. The full example, with the node's manifest, is in an external agent node, end to end.

When the process flow runs, the node hands the external agent its node prompt, the run goal and the context sources that are on for the node. A {{goal}} in the node prompt is filled with the goal you give run-process-flow. Set context_access to {"mode": "off"} for an external agent you do not trust, so that project information does not go to a third party. Poll the run with get-execution, because a node like this can stay open for a long time and can stop to ask a question.

An external agent returns no token usage, so an external step shows only what Wexa spends on its own side. A question from an external agent over mcp is cancelled after 3 minutes with no answer. A question over a2a has no time limit, and no tool cancels a parked run.

Rotate a credential

There is no update operation, so change a secret by replacing the connection.

Register a new connection with the new secret.
Point every interop_agent node at the new connection id with update-process-flow (registration_id).
Delete the old connection with delete-peer-agent.

Do step 2 before step 3: delete-peer-agent refuses while a node still uses the connection.

Result fields

connection_id: the id an interop_agent node takes as registration_id.
name, protocol, endpoint: what you registered.
state: Draft when registered, Active once a call to the external agent has gone through.

The secret is not in the result.

Every tool call works the same way: How every tool call works.