A2A
Publish deployed workflows as agent-to-agent skills and call external A2A agents from workflows.
A2A lets a deployed Confluye workflow act as an agent skill, and lets a workflow call another A2A agent through the A2A Call block.
Exposing deployed workflows
Confluye publishes an agent card at /api/a2a/{workspaceSlug}/agent-card. The card lists deployed
workflows as skills and points clients at /api/a2a/{workspaceSlug}/invoke.
The endpoints require a workspace API key. The key's workspace must match the workspace slug, and
the requested skillId must be a deployed workflow id in that workspace.
The card is not a public publication surface. Every card, invocation, and task-status request requires the bearer workspace key. Reading the card or task requires current read authority; invoking a workflow requires current execute authority. Revoked or downgraded keys lose access immediately.
Synchronous invocation
By default, POST /api/a2a/{workspaceSlug}/invoke runs in sync mode. A successful response is
200 with { runId, status, result }, where result is the workflow Response body when one was
captured, or the run output otherwise.
Synchronous A2A is only for workflows that can finish without durable waits. If the workflow uses a
Wait or Human-in-the-Loop approval block, sync invocation returns 422.
Async tasks
Set mode=async in the request body or query string to create a persisted task:
{
"skillId": "workflow_id",
"mode": "async",
"input": { "customerId": "cus_123" },
"callbackUrl": "https://example.com/a2a/callback"
}
Async invocation returns 202 with:
{
"taskId": "c...",
"status": "pending",
"statusUrl": "https://host/api/a2a/workspace/tasks/c...",
"callbackSecret": "..."
}
Poll the statusUrl with the same bearer API key. Pending tasks return their current state;
completed tasks include result; failed tasks include an error result. Expired tasks return 410.
Async tasks support workflows that park on Wait or approval blocks. The task stays pending while the workflow run is waiting and is reconciled when the run succeeds, fails, or is canceled.
Callbacks
When callbackUrl is provided, Confluye POSTs the terminal task result to that URL. The callback
body includes taskId, runId, status, result, and callbackDelivered.
Callbacks are signed with:
| Header | Meaning |
|---|---|
x-fluxus-a2a-signature | sha256= HMAC of body + timestamp |
x-fluxus-a2a-timestamp | Unix timestamp in seconds used for the signature |
The callbackSecret is returned once in the 202 response and is stored encrypted by Confluye.
Callback delivery uses the same SSRF egress guard as other external HTTP calls and retries up to
three times with exponential backoff.
Calling A2A agents
Use the A2A Call block to invoke another agent from a workflow. Configure the invoke endpoint,
API key, skillId, input payload, timeout, and mode.
In async mode, the block adds mode=async to the endpoint and polls the returned statusUrl until
the task completes, fails, expires, or the configured timeout is reached.