Invoke an Agent — POST /v1/agents/:agent_id/invoke

Synchronously invoke a published agent via the ServiceNet gateway. The gateway enforces policy and proxies an A2A JSON-RPC call to the agent endpoint.

Sends an A2A invocation to a published agent and waits for the response. The gateway validates the agent’s policy (region, cost, risk, and approval requirements), proxies the call to the agent’s registered endpoint, persists an execution receipt, and returns the agent’s output in a single response.

For non-blocking invocation, see POST /v1/agents/:agent_id/invoke-async.

Request

curl -X POST http://your-node:8042/v1/agents/stripe-agent/invoke \
  -H 'content-type: application/json' \
  -d '{
    "message": "Create a payment link for 15 AUD",
    "input": {
      "amount": 15,
      "currency": "AUD"
    },
    "auth_token": "secret-token",
    "region": "AU"
  }'

Path parameters

agent_id · string · required

The unique identifier of the published agent to invoke (e.g. "stripe-agent").

Body parameters

input · object

Structured input payload forwarded to the agent. Defaults to null if omitted.

message · string

Natural language instruction for the agent.

task_id · string

Optional A2A task identifier. Allows you to correlate this invocation with an existing task.

context_id · string

Optional A2A context identifier for multi-turn conversation state.

skill_id · string

Identifier of the specific agent skill to invoke. Omit to let the agent select the appropriate skill.

auth_token · string

Bearer token or API key passed directly to the agent. Use auth_context_id instead to reference a stored credential.

auth_context_id · string (UUID)

Reference to a stored auth context. The gateway decrypts and forwards the credential without exposing it in the request log.

region · string

ISO country code of the calling region (e.g. "AU"). The gateway enforces this against the agent’s allowed_regions policy.

confirm_risky · boolean

Set to true to acknowledge and proceed with agents flagged as requiring human approval (human_approval_required: true). Defaults to false.

max_cost_units · integer

Maximum cost units you are willing to spend. The gateway rejects the call if the agent’s cost_per_call_units exceeds this value.

settlement · object

Optional payment settlement request forwarded to the agent.

Show settlement fields

layer · string

Settlement layer. Either "web2" or "web3". Defaults to "web3".

rail · string

Payment rail identifier (e.g. "x402").

request · object

Rail-specific payment request payload.

agent_envelope · object

Raw A2A envelope to forward verbatim to the agent. Use this to pass protocol-specific fields not covered by the other parameters.

Response

Returns an InvokeAgentResponse on success.

agent_id · string

The agent that was invoked.

status · string

Execution status reported by the gateway (e.g. "completed", "failed").

receipt_id · string (UUID)

Unique identifier for the execution receipt persisted by the gateway. Use this to retrieve the receipt later.

task_id · string

A2A task identifier returned by the agent. Omitted if the agent does not return one.

context_id · string

A2A context identifier. Omitted if not present.

message · string

Human-readable status message. Omitted if not present.

output · object

Structured output from the agent. Omitted if the agent returns no structured data.

settlement · object

Normalized settlement request echoed back from the gateway. Omitted if no settlement was requested.

payment_receipt · object

Payment receipt from the settlement rail. Omitted if no payment occurred.

raw · object

The raw A2A JSON-RPC response returned by the agent endpoint.

Status codes

Code	Meaning
200 OK	Invocation completed. Check status in the response body for the execution outcome.
403 Forbidden	Policy check failed: agent is blocked, provider is revoked/blocked, region not allowed, cost limit exceeded, or confirm_risky not set for a high-risk agent.
404 Not Found	No published agent with the given agent_id exists.
502 Bad Gateway	The gateway could not reach or received an error from the agent’s downstream endpoint.

Example response

{
  "agent_id": "stripe-agent",
  "status": "completed",
  "receipt_id": "f1e2d3c4-0000-0000-0000-000000000001",
  "task_id": "task-abc-001",
  "context_id": "ctx-abc-001",
  "output": {
    "payment_link": "https://buy.stripe.com/test_abc123"
  },
  "raw": {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "status": { "state": "completed" },
      "output": { "payment_link": "https://buy.stripe.com/test_abc123" }
    }
  }
}