Invoke a Published Agent via the ServiceNet Gateway

Call a published agent through the Watt ServiceNet gateway. The gateway enforces policy then forwards your request as an A2A JSON-RPC call.

Once an agent is published, call it by sending POST /v1/agents/{agent_id}/invoke. The gateway runs a series of policy checks—provider status, blocklist, authentication, region, cost, and risk—and then forwards your request to the agent’s registered endpoint as an A2A SendMessage JSON-RPC call. The call blocks until the agent responds and returns the result directly in the HTTP response.

Basic Invocation

curl -X POST http://127.0.0.1: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"
  }'

A successful invocation returns 200 OK:

{
  "agent_id": "stripe-agent",
  "status": "TASK_STATE_COMPLETED",
  "receipt_id": "550e8400-e29b-41d4-a716-446655440000",
  "task_id": "task-1",
  "context_id": "ctx-1",
  "message": "Payment link created",
  "output": { "payment_link": "https://buy.stripe.com/..." },
  "raw": { "jsonrpc": "2.0", "result": { "task": { ... } } }
}

The raw field contains the unmodified A2A JSON-RPC response from the agent for debugging or advanced parsing.

Request Fields

message · string

Free-text message to send to the agent. Serialized as an A2A text message part.

input · object

Structured data payload. Serialized as an A2A data message part alongside message if both are provided.

auth_token · string

Bearer token for the agent. Required when the agent’s securitySchemes declares any scheme other than none. The gateway passes this as an Authorization: Bearer header to the agent endpoint.

auth_context_id · string (UUID)

ID of a stored auth context registered via /v1/auth-contexts/register. Use this instead of auth_token to avoid passing raw credentials in every request. The gateway resolves the stored token at invocation time.

region · string

ISO 3166-1 alpha-2 country code (e.g. "AU", "US"). Required when the agent’s review profile has a non-empty allowed_regions list. The gateway rejects the call if the region does not match.

confirm_risky · boolean · default: "false"

Must be true to invoke agents with risk_level: "high". Provides an explicit acknowledgement that the caller understands the risk.

max_cost_units · integer

Maximum cost units the caller is willing to pay. If the agent’s declared cost field in its agent card exceeds this value, the gateway rejects the call before forwarding.

task_id · string

A2A task ID to continue an existing task. Maps to the taskId field in the A2A SendMessage payload.

context_id · string

A2A context ID for multi-turn conversations. Maps to contextId in the A2A payload.

skill_id · string

Target a specific skill on the agent. Maps to skillId in the A2A payload. If omitted, the agent chooses the default skill.

settlement · object

Optional payment settlement request forwarded to the agent via the A2A extensions field. See Settlement (x402) below.

agent_envelope · object

Arbitrary extension data forwarded to the agent in the A2A extensions.agent_envelope field. Use this to pass caller identity, source agent cards, or custom context.

Response Fields

agent_id · string

The agent that was invoked.

status · string

A2A task state string from the agent response. Common values: TASK_STATE_COMPLETED, TASK_STATE_WORKING, TASK_STATE_FAILED, TASK_STATE_UNKNOWN.

receipt_id · string (UUID)

ServiceNet execution receipt ID. Use GET /v1/receipts/{receipt_id} to fetch the stored receipt and its verification status.

task_id · string

The A2A task ID returned by the agent. Pass this in subsequent invocations to continue the task.

context_id · string

The A2A context ID returned by the agent.

message · string

The last text message part extracted from the agent’s response.

output · object

The first data artifact part extracted from the agent’s response. For agents that return structured data, this is the primary result field.

settlement · object

The normalized settlement request forwarded to the agent, if one was provided.

payment_receipt · object

Payment receipt extracted from the agent’s response artifacts, if present.

raw · object

The full, unmodified A2A JSON-RPC response body from the agent.

Policy Enforcement

The gateway runs the following checks in order before forwarding the call. Any failure returns 403 Forbidden immediately.

1. Provider status

   The agent’s provider must exist and not be in revoked status. Revoked providers cannot serve invocations.

2. Provider blocklist

   The provider must not be on the trust blocklist. Blocked providers are prevented from serving calls while an investigation is open.

3. Agent blocklist

   The agent itself must not be blocked. Individual agents can be blocked without affecting other agents under the same provider.

4. Authentication check

   If the agent’s securitySchemes declares any scheme other than none, either auth_token or auth_context_id must be present. A missing token results in a 403 with "auth token or auth context is required".

5. Region check

   If the agent’s review profile has a non-empty allowed_regions list, the region field must be present and match one of the allowed values (case-insensitive). A missing or mismatched region results in 403.

6. Cost check

   If max_cost_units is provided in the request (or a default is configured on the node via SERVICENET_GATEWAY_MAX_COST_UNITS), and the agent’s declared cost field in its agent card exceeds that limit, the gateway returns 403 with "agent cost exceeds caller budget".

7. Risk confirmation

   If the agent’s risk_level is "high", the request must include "confirm_risky": true. Omitting this flag results in 403 with "high-risk agent requires explicit confirmation".

Settlement (x402)

The settlement field allows you to attach a Web3 payment alongside the invocation. The gateway normalizes the request and forwards it to the agent inside the A2A extensions.settlement field.

"settlement": {
  "layer": "web3",
  "rail": "x402",
  "request": {
    "pay_to": "0xabc123"
  }
}

The gateway currently supports the x402 rail on the web3 layer. The request object is passed through to the agent after normalization (adding a "protocol": "x402" field if absent).

web2 settlement rails are not yet implemented. Submitting a web2 settlement request returns 403 Forbidden.

Error Reference

HTTP Status	Condition
403 Forbidden	Provider revoked or blocked; agent blocked; auth token missing; region not allowed; cost exceeded; high-risk not confirmed
404 Not Found	Agent not found in the published registry
502 Bad Gateway	The downstream agent returned an HTTP error, a non-JSON body, or an A2A error object; or the connection timed out or was refused

A 502 means the gateway reached the agent’s registered endpoint but the call failed. Check the error field in the response body for a detailed diagnostic message including the A2A method, agent ID, and failure classification.