Invoke Agent Async — POST /v1/agents/:agent_id/invoke-async

Submit an agent invocation without blocking. Returns a receipt_id with status ‘running’. Poll the receipt endpoint to check when the call completes.

Submits an agent invocation and returns immediately without waiting for the agent to complete. The gateway accepts the invocation, issues a receipt_id, and executes the call in the background. Use the returned receipt_id with the receipts API to poll for completion.

This endpoint accepts exactly the same request body as POST /v1/agents/:agent_id/invoke.

Request

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

Path parameters

agent_id · string · required

The unique identifier of the published agent to invoke.

Body parameters

All body parameters are identical to POST /v1/agents/:agent_id/invoke.

input · object

Structured input payload forwarded to the agent.

message · string

Natural language instruction for the agent.

task_id · string

Optional A2A task identifier.

context_id · string

Optional A2A context identifier for multi-turn conversation state.

skill_id · string

Identifier of the specific agent skill to invoke.

auth_token · string

Bearer token or API key passed directly to the agent.

auth_context_id · string (UUID)

Reference to a stored auth context.

region · string

ISO country code of the calling region.

confirm_risky · boolean

Set to true to proceed with agents that require human approval. Defaults to false.

max_cost_units · integer

Maximum cost units you are willing to spend on this call.

settlement · object

Optional payment settlement request.

Show settlement fields

layer · string

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.

Response

Returns an InvokeAgentResponse immediately with status set to "running".

agent_id · string

The agent that was invoked.

status · string

Always "running" for an async invocation. The call is still in progress.

receipt_id · string (UUID)

Unique identifier for the in-progress execution receipt. Poll GET /v1/receipts/:receipt_id to check when the status transitions to "succeeded" or "failed".

message · string

Always "ServiceNet invocation accepted" for a successful async submission.

raw · object

Empty object at submission time. Populated on the receipt record once execution completes.

Status codes

Code	Meaning
200 OK	Invocation accepted. Returns the initial InvokeAgentResponse with status: "running".
403 Forbidden	Policy check failed before the invocation could be queued.
404 Not Found	No published agent with the given agent_id exists.
502 Bad Gateway	The gateway could not dispatch the invocation to the downstream agent endpoint.

Example response

{
  "agent_id": "stripe-agent",
  "status": "running",
  "receipt_id": "f1e2d3c4-0000-0000-0000-000000000002",
  "message": "ServiceNet invocation accepted",
  "raw": {}
}

After receiving this response, poll GET /v1/receipts/f1e2d3c4-0000-0000-0000-000000000002 to retrieve the execution outcome once status changes from "running" to "succeeded" or "failed".