> ## Documentation Index
> Fetch the complete documentation index at: https://hs-df36fa00.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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`:

```json theme={null}
{
  "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

<ParamField body="message" type="string">
  Free-text message to send to the agent. Serialized as an A2A `text` message part.
</ParamField>

<ParamField body="input" type="object">
  Structured data payload. Serialized as an A2A `data` message part alongside `message` if both are provided.
</ParamField>

<ParamField body="auth_token" type="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.
</ParamField>

<ParamField body="auth_context_id" type="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.
</ParamField>

<ParamField body="region" type="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.
</ParamField>

<ParamField body="confirm_risky" type="boolean" default="false">
  Must be `true` to invoke agents with `risk_level: "high"`. Provides an explicit acknowledgement that the caller understands the risk.
</ParamField>

<ParamField body="max_cost_units" type="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.
</ParamField>

<ParamField body="task_id" type="string">
  A2A task ID to continue an existing task. Maps to the `taskId` field in the A2A `SendMessage` payload.
</ParamField>

<ParamField body="context_id" type="string">
  A2A context ID for multi-turn conversations. Maps to `contextId` in the A2A payload.
</ParamField>

<ParamField body="skill_id" type="string">
  Target a specific skill on the agent. Maps to `skillId` in the A2A payload. If omitted, the agent chooses the default skill.
</ParamField>

<ParamField body="settlement" type="object">
  Optional payment settlement request forwarded to the agent via the A2A `extensions` field. See [Settlement (x402)](#settlement-x402) below.
</ParamField>

<ParamField body="agent_envelope" type="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.
</ParamField>

## Response Fields

<ResponseField name="agent_id" type="string">
  The agent that was invoked.
</ResponseField>

<ResponseField name="status" type="string">
  A2A task state string from the agent response. Common values: `TASK_STATE_COMPLETED`, `TASK_STATE_WORKING`, `TASK_STATE_FAILED`, `TASK_STATE_UNKNOWN`.
</ResponseField>

<ResponseField name="receipt_id" type="string (UUID)">
  ServiceNet execution receipt ID. Use `GET /v1/receipts/{receipt_id}` to fetch the stored receipt and its verification status.
</ResponseField>

<ResponseField name="task_id" type="string">
  The A2A task ID returned by the agent. Pass this in subsequent invocations to continue the task.
</ResponseField>

<ResponseField name="context_id" type="string">
  The A2A context ID returned by the agent.
</ResponseField>

<ResponseField name="message" type="string">
  The last text message part extracted from the agent's response.
</ResponseField>

<ResponseField name="output" type="object">
  The first data artifact part extracted from the agent's response. For agents that return structured data, this is the primary result field.
</ResponseField>

<ResponseField name="settlement" type="object">
  The normalized settlement request forwarded to the agent, if one was provided.
</ResponseField>

<ResponseField name="payment_receipt" type="object">
  Payment receipt extracted from the agent's response artifacts, if present.
</ResponseField>

<ResponseField name="raw" type="object">
  The full, unmodified A2A JSON-RPC response body from the agent.
</ResponseField>

## Policy Enforcement

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

<Steps>
  <Step title="Provider status">
    The agent's provider must exist and not be in `revoked` status. Revoked providers cannot serve invocations.
  </Step>

  <Step title="Provider blocklist">
    The provider must not be on the trust blocklist. Blocked providers are prevented from serving calls while an investigation is open.
  </Step>

  <Step title="Agent blocklist">
    The agent itself must not be blocked. Individual agents can be blocked without affecting other agents under the same provider.
  </Step>

  <Step title="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"`.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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"`.
  </Step>

  <Step title="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"`.
  </Step>
</Steps>

## 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.

```json theme={null}
"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).

<Note>
  `web2` settlement rails are not yet implemented. Submitting a `web2` settlement request returns `403 Forbidden`.
</Note>

## 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 |

<Warning>
  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.
</Warning>