Calling the A2A agent

Available bindings for A2A calls

All A2A calls go to one of the following bindings on the Textual host:

Binding type	Endpoint	Description
JSON-RPC	POST /a2a	The default binding. Used by A2A v0.3 clients.
REST (HTTP+JSON)	POST /a2a/v1/message:send GET /a2a/v1/tasks/{id}	Only available when the protocol mode is either both or v1_only.

Both bindings require Authorization: Bearer <token>.

The token can be either a Textual API key or an OAuth access token.

Using a Textual API key

When you use a Textual API key, you put the key directly in the header.

API keys do not expire, but they can be revoked.

curl https://<host>/a2a \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id":      1,
    "method":  "message/send",
    "params": {
      "message": {
        "role":      "user",
        "messageId": "msg-1",
        "parts":     [{"kind": "text", "text": "/detect John Smith lives at 123 Main St."}]
      }
    }
  }'

Using an OAuth2 access token

Drive the authorization-code flow against the OAuth2 endpoints advertised in the agent card, then use the resulting access token exactly like an API key.

OAuth2 access tokens live for one hour. They cannot be refreshed. When a token expires, re-run the authorization code flow.

Authentication flow

Starting the request

import base64, hashlib, secrets, urllib.parse, webbrowser
import requests

BASE   = "https://textual.example.com"
CLIENT = ("PyFXmPVxAx9hKL3", "CpWEPmPVxAx9hKL3NcP9XjqBz6_5JmQsL8kZx2gYaH0")  # (clientId, clientSecret)
REDIR  = "https://your-app.example.com/oauth/callback"

For a client from an A2A-compliant marketplace clients, steps to get the access code and generate the access token occur automatically. You can then Make the call to /a2a with the access token.

Otherwise, continue to Get an access code.

Get an access code

Next, redirect the user to /authorize to complete the approval and obtain the access code.

To use PKCE, send code_challenge + code_challenge_method=S256.

verifier  = secrets.token_urlsafe(64)
challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
params = {
    "response_type":         "code",
    "client_id":             CLIENT[0],
    "redirect_uri":          REDIR,
    "scope":                 "a2a",
    "state":                 secrets.token_urlsafe(16),
    "code_challenge":        challenge,
    "code_challenge_method": "S256",
}
webbrowser.open(f"{BASE}/api/v1/a2a/oauth/authorize?{urllib.parse.urlencode(params)}")
code = input("paste ?code=... from the redirect URL: ")

Obtain the access token

Next, exchange the access code for an access token.

To use PKCE, send the matching code_verifier.

token = requests.post(
    f"{BASE}/api/v1/a2a/oauth/token",
    data={
        "grant_type":    "authorization_code",
        "code":          code,
        "redirect_uri":  REDIR,
        "code_verifier": verifier,
    },
    auth=CLIENT,  # HTTP Basic
).json()["access_token"]

Make the call to /a2a with the access token

Finally, you use the token to make the call to the agent in the same way as you would with an API key:

resp = requests.post(
    f"{BASE}/a2a",
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
    json={
        "jsonrpc": "2.0", "id": 1, "method": "message/send",
        "params": {"message": {"role": "user", "messageId": "m1",
                               "parts": [{"kind": "text", "text": "/redact John Smith, SSN 123-45-6789"}]}}
    },
).json()

Selecting the protocol version

In the header, to determine the version of the A2A protocol to use:

• To use the v1 format, send A2A-Version: 1.0

• To use the v.03 format, either

  • Send A2A-Version: 0.3

  • Do not provide a version in the header.

Task lifecycle

Each task progress through the standard A2A states: submitted → working → completed / failed / canceled.

When you use tasks/cancel to cancel a file-redact task, the cancellation propagates to the underlying Textual job.

Once a a pii-detect or pii-redact task is completed, the cancellation has no effect.

Completed, failed, and canceled tasks are purged after SOLAR_A2A_TASK_TTL_HOURS. The default is 72 hours.

Active tasks are never purged.

About the response

The response contains a task object with an id and a list of artifacts.

• For pii-detect and pii-redact, the artifact is inline.

• For file-redact, the task is asynchronous and the client polls or subscribes for the completion event.