> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# A2A Quickstart
> Get started with StackOne's A2A agents with the A2A UI, and use cURL to retrieve an Agent Card, send a Message, and get a Task.
## Overview
StackOne provides an A2A agent for your linked StackOne accounts at:
```bash theme={null}
https://a2a.stackone.com
```
**Authentication**: All requests require Basic authentication (`Authorization` header with base64-encoded API key) and your StackOne account ID (`x-account-id` header), with the exception of the public agent card routes such as `/.well-known/agent-card.json`, which need no authentication.
This guide walks you through the basic A2A operations to help you understand the protocol before integrating with your preferred agent framework.
***
## Quick Testing Options
Choose your preferred testing method to get started with StackOne's A2A agents:
### Interactive Testing Interface
You can go to [a2a-ui.stackone.com](https://a2a-ui.stackone.com) and interact with StackOne agents directly in your browser.
**Getting Started:**
1. Go to [a2a-ui.stackone.com](https://a2a-ui.stackone.com)
2. Click the gear "⚙️" icon and enter your StackOne API key and account ID. For multiple accounts, enter the account IDs comma-separated with no spaces (for example `id1,id2`). Click anywhere outside the modal to dismiss it (see our [Authentication Guide](/a2a/auth-security) for details)
3. Click the "+ Agent" button, enter the StackOne agent card URL `https://a2a.stackone.com/.well-known/agent-card.json`, and click "Add Agent"
4. Start chatting with the agent!
The agent's skills reflect your account's configured integrations and enabled actions. The UI reads the public agent card and then fetches your account-specific skills using the credentials you entered.
This is the fastest way to test A2A functionality without any setup!
### Programmatic Testing
Perfect for developers who prefer command-line tools or want to integrate A2A into scripts.
#### Step 1: Get the Agent Card
StackOne serves two agent cards. The **public discovery card** at `/.well-known/agent-card.json` describes the agent in general and needs no authentication; it advertises `supportsAuthenticatedExtendedCard: true`. The **authenticated extended card** at `/agent/authenticatedExtendedCard` is specific to your account and lists the skills for your connected integrations. A2A clients such as the A2A UI and the A2A SDKs read the public card and then fetch the extended card automatically.
Fetch the public discovery card (no authentication required):
```bash theme={null}
curl -X GET https://a2a.stackone.com/.well-known/agent-card.json
```
**Example response:**
```json theme={null}
{
"name": "StackOne",
"description": "StackOne A2A agent. Authenticate with a StackOne API key and account ID to discover account-specific capabilities via the agent/authenticatedExtendedCard endpoint.",
"protocolVersion": "0.3.4",
"version": "0.1.0",
"url": "https://a2a.stackone.com",
"capabilities": {
"streaming": true
},
"defaultInputModes": ["text/plain"],
"defaultOutputModes": ["text/plain"],
"supportsAuthenticatedExtendedCard": true
}
```
Fetch the account-specific extended card with your credentials:
```bash theme={null}
curl -X GET https://a2a.stackone.com/agent/authenticatedExtendedCard \
-H 'Authorization: Basic ' \
-H 'x-account-id: '
```
**Example response** (skills reflect your connected integrations):
```json theme={null}
{
"name": "StackOne (1 connector)",
"description": "A StackOne agent with access to: HiBob.",
"protocolVersion": "0.3.4",
"version": "0.1.0",
"url": "https://a2a.stackone.com",
"skills": [
{
"id": "hibob_list_employees",
"name": "List Employees",
"description": "Get a list of employees",
"tags": ["stackone", "hibob"]
},
{
"id": "hibob_get_employee",
"name": "Get Employee",
"description": "Get details of a specific employee",
"tags": ["stackone", "hibob"]
}
],
"capabilities": {
"streaming": true
},
"defaultInputModes": ["text/plain"],
"defaultOutputModes": ["text/plain"]
}
```
**Agent Card Routes:**
* **For connecting to agents:** point your client at `https://a2a.stackone.com/.well-known/agent-card.json`. A2A clients read this public card and then fetch your account-specific skills from the authenticated extended card at `https://a2a.stackone.com/agent/authenticatedExtendedCard`.
* **For viewing a connector's skills:** connector-specific routes like `https://a2a.stackone.com/hibob/agent-card.json` are public reference cards for inspecting one connector's skills. They are for reference only and should not be used for agent connections.
***
#### Step 2: Send a Message
The `message/send` method sends a message to an agent to initiate a new interaction or continue an existing one. Each message requires a unique `messageId` (a UUID):
Replace `messageId` with a unique UUID for each request. On macOS/Linux: `uuidgen | tr '[:upper:]' '[:lower:]'`
```bash theme={null}
curl -X POST https://a2a.stackone.com \
-H 'Authorization: Basic ' \
-H 'x-account-id: ' \
-H 'Content-Type: application/json' \
-d '{
"jsonrpc": "2.0",
"id": "msg-1",
"method": "message/send",
"params": {
"message": {
"messageId": "550e8400-e29b-41d4-a716-446655440000",
"role": "user",
"parts": [
{
"kind": "text",
"text": "List the first 10 employees"
}
],
"kind": "message"
},
"configuration": {
"blocking": true
}
}
}'
```
**Expected Response:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": "msg-1",
"result": {
"id": "task-123",
"contextId": "ctx-456",
"kind": "task",
"status": {
"state": "completed",
"timestamp": "2026-01-01T00:00:00.000000+00:00"
},
"artifacts": [
{
"artifactId": "artifact-1",
"parts": [
{
"kind": "text",
"text": "Here are the first 10 employees:\n1. John Doe - Software Engineer\n2. Jane Smith - Product Manager\n3. Bob Johnson - HR Specialist\n..."
}
]
}
],
"history": [
{
"role": "user",
"parts": [
{
"kind": "text",
"text": "List the first 10 employees"
}
]
}
]
}
}
```
Pass `"configuration": { "blocking": false }` and poll `tasks/get` continuously for long-running operations.
***
#### Step 3: Get Task Status
Use `tasks/get` to retrieve the current state of a task (useful for long-running operations):
```bash theme={null}
curl -X POST https://a2a.stackone.com \
-H 'Authorization: Basic ' \
-H 'x-account-id: ' \
-H 'Content-Type: application/json' \
-d '{
"jsonrpc": "2.0",
"id": "task-query-1",
"method": "tasks/get",
"params": {
"id": "task-123"
}
}'
```
**Expected Response:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": "task-query-1",
"result": {
"id": "task-123",
"contextId": "ctx-456",
"kind": "task",
"status": {
"state": "completed",
"timestamp": "2026-01-01T00:00:00.000000+00:00"
},
"artifacts": [
{
"artifactId": "artifact-1",
"parts": [
{
"kind": "text",
"text": "Here are the first 10 employees:\n1. John Doe - Software Engineer\n2. Jane Smith - Product Manager\n3. Bob Johnson - HR Specialist\n..."
}
]
}
],
"history": [
{
"role": "user",
"parts": [
{
"kind": "text",
"text": "List the first 10 employees"
}
]
}
]
}
}
```
## Next Steps
Now that you understand the basic A2A operations, choose your integration path:
Use the official A2A SDKs to build your own tools
Build agents in frameworks with A2A integrations
## Common Issues & Solutions
Verify your API key is correctly base64 encoded in the Authorization header
Confirm that the `x-account-id` header matches your linked account ID, and ensure the account belongs to the same project as your API key
Remember: A2A does not support query parameters for authentication, only headers
Check that the account is active (i.e., is not in an error state or otherwise disabled)
Verify your integrations are properly configured (agent skills are generated based on the enabled actions for the integration configuration associated with the linked account)