Skip to main content

​
Overview

StackOne provides an A2A agent for your linked StackOne accounts at: 
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:

​
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

Now that you understand the basic A2A operations, choose your integration path:

A2A SDK

Use the official A2A SDKs to build your own tools

Agent Guides

Build agents in frameworks with A2A integrations

​
Common Issues & Solutions

1
Verify your API key is correctly base64 encoded in the Authorization header
2
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
3
Remember: A2A does not support query parameters for authentication, only headers
1
Check that the account is active (i.e., is not in an error state or otherwise disabled)
2
Verify your integrations are properly configured (agent skills are generated based on the enabled actions for the integration configuration associated with the linked account)