A2A Quickstart

🎮 StackOne A2A UI (Recommended)

Interactive Testing Interface

You can go to a2a-ui.stackone.com and interact with StackOne agents directly in your browser.Getting Started:

Go to a2a-ui.stackone.com
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 for details)
Click the ”+ Agent” button, enter the StackOne agent card URL https://a2a.stackone.com/.well-known/agent-card.json, and click “Add Agent”
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!

💻 cURL Testing (Command Line)

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):

curl -X GET https://a2a.stackone.com/.well-known/agent-card.json

Example response:

{
  "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:

curl -X GET https://a2a.stackone.com/agent/authenticatedExtendedCard \
  -H 'Authorization: Basic <BASE64_APIKEY_COLON>' \
  -H 'x-account-id: <ACCOUNT_ID>'

Example response (skills reflect your connected integrations):

{
  "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:]'

curl -X POST https://a2a.stackone.com \
  -H 'Authorization: Basic <BASE64_APIKEY_COLON>' \
  -H 'x-account-id: <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:

{
  "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):

curl -X POST https://a2a.stackone.com \
  -H 'Authorization: Basic <BASE64_APIKEY_COLON>' \
  -H 'x-account-id: <ACCOUNT_ID>' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "task-query-1",
    "method": "tasks/get",
    "params": {
      "id": "task-123"
    }
  }'

Expected Response:

{
  "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

A2A SDK

Use the official A2A SDKs to build your own tools

Agent Guides

Build agents in frameworks with A2A integrations

Common Issues & Solutions

401/403 Authentication Error

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

Agent has no skills

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)

Getting Started

Agent Frameworks

Agent Platforms

Overview

Quick Testing Options

Interactive Testing Interface

Programmatic Testing

Step 1: Get the Agent Card

Step 2: Send a Message

Step 3: Get Task Status

Next Steps

A2A SDK

Agent Guides

Common Issues & Solutions

​Overview

​Quick Testing Options

​Interactive Testing Interface

​Programmatic Testing

​Step 1: Get the Agent Card

​Step 2: Send a Message

​Step 3: Get Task Status

​Next Steps

A2A SDK

Agent Guides

​Common Issues & Solutions

Overview

Quick Testing Options

Interactive Testing Interface

Programmatic Testing

Step 1: Get the Agent Card

Step 2: Send a Message

Step 3: Get Task Status

Next Steps

Common Issues & Solutions