Async Agent Invocation, Receipt Polling, and Task Status

Submit non-blocking agent invocations via invoke-async, then poll the ServiceNet receipt or A2A task endpoint to get the final result.

For long-running agent calls, use POST /v1/agents/{agent_id}/invoke-async. The gateway applies the same policy checks as synchronous invocation, then accepts the call immediately and returns a receipt_id with status: "running". The actual A2A SendMessage call executes in the background, and the receipt is updated with the final outcome when it completes.

Submit an Async Invocation

The request body is identical to the synchronous /invoke endpoint. You pass the same fields for auth, region, risk, cost, and settlement.

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

The gateway responds immediately with 200 OK:

{
  "agent_id": "stripe-agent",
  "status": "running",
  "receipt_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "ServiceNet invocation accepted"
}

Save the receipt_id. You will use it to poll for the result.

Poll the Receipt

GET /v1/receipts/{receipt_id} returns the current state of the execution receipt. Poll it until status transitions from "running" to either "succeeded" or "failed".

curl http://127.0.0.1:8042/v1/receipts/550e8400-e29b-41d4-a716-446655440000

Running receipt (invocation still in progress):

{
  "receipt": {
    "receipt_id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_id": "stripe-agent",
    "provider_id": "acme-labs",
    "status": "running",
    "verification": "not_required",
    "request_digest": "a3f1b2c4...",
    "started_at": "2025-01-15T10:00:00Z"
  }
}

Completed receipt (invocation finished):

{
  "receipt": {
    "receipt_id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_id": "stripe-agent",
    "provider_id": "acme-labs",
    "status": "succeeded",
    "verification": "pending",
    "request_digest": "a3f1b2c4...",
    "result_digest": "d9e8f7a6...",
    "started_at": "2025-01-15T10:00:00Z",
    "completed_at": "2025-01-15T10:00:03Z",
    "cost_units": 5
  },
  "output": { ... }
}

Receipt Status Values

Status	Meaning
running	Background invocation is in progress
succeeded	Agent responded successfully
failed	Agent returned an error or the connection failed; see stderr on the stored receipt
rejected	Gateway rejected the invocation before it was submitted to the agent

Receipt Verification Values

Verification	Meaning
not_required	Agent has risk_level: "low"; no verification sweep needed
pending	Receipt is queued for the automated verifier sweep
verified	Verification passed
failed	Verification failed

Get an A2A Task

If the agent returns a task_id (visible in the synchronous response or a completed receipt’s output), you can poll the live task state directly using POST /v1/agents/{agent_id}/tasks/{task_id}/get.

curl -X POST http://127.0.0.1:8042/v1/agents/stripe-agent/tasks/task-123/get \
  -H 'content-type: application/json' \
  -d '{
    "history_length": 10,
    "auth_token": "secret-token"
  }'

The gateway forwards a GetTask JSON-RPC call to the agent’s registered endpoint and returns the result in the same InvokeAgentResponse envelope as a regular invocation.

history_length · integer

Number of historical messages to include in the task response. Defaults to 10 if omitted.

auth_token · string

Bearer token for the agent, if required. The same auth rules apply as for invocation.

auth_context_id · string (UUID)

Reference to a stored auth context as an alternative to a raw auth_token.

Listing and Querying Receipts

Fetch all receipts for a specific agent or provider:

# All receipts for an agent
curl "http://127.0.0.1:8042/v1/receipts?agent_id=stripe-agent"

# All receipts for a provider
curl "http://127.0.0.1:8042/v1/receipts?provider_id=acme-labs"

You can also filter by verification verdict:

curl "http://127.0.0.1:8042/v1/receipts?agent_id=stripe-agent&verification=pending"

Sync vs Async Comparison

	/invoke	/invoke-async
Blocks until agent responds	Yes	No
Returns output directly	Yes	No — poll receipt
receipt_id returned	Yes	Yes
Initial status	A2A task state (e.g. TASK_STATE_COMPLETED)	"running"
Task polling via /tasks/:id/get	Yes (use task_id from response)	Yes (use task_id from completed receipt)
Suitable for long-running agents	Risk of HTTP timeout	Yes

Use invoke-async whenever your agent might take more than a few seconds to respond. A synchronous HTTP connection holding open for a long-running agent risks client-side timeouts, proxy cuts, or load-balancer drops. Async invocations are stored server-side and survive any transient network disruption.