> ## 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 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](/api/agents/invoke-async).

## Request

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

<ParamField path="agent_id" type="string" required>
  The unique identifier of the published agent to invoke (e.g. `"stripe-agent"`).
</ParamField>

### Body parameters

<ParamField body="input" type="object">
  Structured input payload forwarded to the agent. Defaults to `null` if omitted.
</ParamField>

<ParamField body="message" type="string">
  Natural language instruction for the agent.
</ParamField>

<ParamField body="task_id" type="string">
  Optional A2A task identifier. Allows you to correlate this invocation with an existing task.
</ParamField>

<ParamField body="context_id" type="string">
  Optional A2A context identifier for multi-turn conversation state.
</ParamField>

<ParamField body="skill_id" type="string">
  Identifier of the specific agent skill to invoke. Omit to let the agent select the appropriate skill.
</ParamField>

<ParamField body="auth_token" type="string">
  Bearer token or API key passed directly to the agent. Use `auth_context_id` instead to reference a stored credential.
</ParamField>

<ParamField body="auth_context_id" type="string (UUID)">
  Reference to a stored auth context. The gateway decrypts and forwards the credential without exposing it in the request log.
</ParamField>

<ParamField body="region" type="string">
  ISO country code of the calling region (e.g. `"AU"`). The gateway enforces this against the agent's `allowed_regions` policy.
</ParamField>

<ParamField body="confirm_risky" type="boolean">
  Set to `true` to acknowledge and proceed with agents flagged as requiring human approval (`human_approval_required: true`). Defaults to `false`.
</ParamField>

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

<ParamField body="settlement" type="object">
  Optional payment settlement request forwarded to the agent.

  <Expandable title="settlement fields">
    <ParamField body="layer" type="string">
      Settlement layer. Either `"web2"` or `"web3"`. Defaults to `"web3"`.
    </ParamField>

    <ParamField body="rail" type="string">
      Payment rail identifier (e.g. `"x402"`).
    </ParamField>

    <ParamField body="request" type="object">
      Rail-specific payment request payload.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="agent_envelope" type="object">
  Raw A2A envelope to forward verbatim to the agent. Use this to pass protocol-specific fields not covered by the other parameters.
</ParamField>

## Response

Returns an `InvokeAgentResponse` on success.

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

<ResponseField name="status" type="string">
  Execution status reported by the gateway (e.g. `"completed"`, `"failed"`).
</ResponseField>

<ResponseField name="receipt_id" type="string (UUID)">
  Unique identifier for the execution receipt persisted by the gateway. Use this to retrieve the receipt later.
</ResponseField>

<ResponseField name="task_id" type="string">
  A2A task identifier returned by the agent. Omitted if the agent does not return one.
</ResponseField>

<ResponseField name="context_id" type="string">
  A2A context identifier. Omitted if not present.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message. Omitted if not present.
</ResponseField>

<ResponseField name="output" type="object">
  Structured output from the agent. Omitted if the agent returns no structured data.
</ResponseField>

<ResponseField name="settlement" type="object">
  Normalized settlement request echoed back from the gateway. Omitted if no settlement was requested.
</ResponseField>

<ResponseField name="payment_receipt" type="object">
  Payment receipt from the settlement rail. Omitted if no payment occurred.
</ResponseField>

<ResponseField name="raw" type="object">
  The raw A2A JSON-RPC response returned by the agent endpoint.
</ResponseField>

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

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