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

# 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`](/guides/invoke-agent) endpoint. You pass the same fields for auth, region, risk, cost, and settlement.

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

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

```bash theme={null}
curl http://127.0.0.1:8042/v1/receipts/550e8400-e29b-41d4-a716-446655440000
```

**Running receipt** (invocation still in progress):

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

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

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

<ParamField body="history_length" type="integer">
  Number of historical messages to include in the task response. Defaults to `10` if omitted.
</ParamField>

<ParamField body="auth_token" type="string">
  Bearer token for the agent, if required. The same auth rules apply as for invocation.
</ParamField>

<ParamField body="auth_context_id" type="string (UUID)">
  Reference to a stored auth context as an alternative to a raw `auth_token`.
</ParamField>

## Listing and Querying Receipts

Fetch all receipts for a specific agent or provider:

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

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

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