Skip to main content

​
Overview

StackOne provides an A2A agent for each integration 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). 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 an Agent Card

Before interacting with an agent, you can fetch its Agent Card to understand its capabilities, skills, and authentication requirements. Agent Cards are available at the standard .well-known URI path:
curl -X GET https://a2a.stackone.com/.well-known/agent-card.json \
  -H 'Authorization: Basic <BASE64_APIKEY_COLON>' \
  -H 'x-account-id: <ACCOUNT_ID>'
Example Response:
{
  "name": "StackOne HiBob",
  "description": "HiBob connector",
  "iconUrl": "https://stackone-logos.com/api/hibob/filled/png",
  "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",
      ]
    },
    {
      "id": "hibob_update_employee",
      "name": "Update Employee",
      "description": "Update Employee Information",
      "tags": [
        "stackone",
        "hibob",
      ]
    }
  ],
  "capabilities": {
    "streaming": true
  },
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ]
}
The response you get from https://a2a.stackone.com/.well-known/agent-card.json will depend on the Authorization and x-account-id headers you use. The A2A agent is dynamically generated based on your account’s configured integrations and enabled actions.
Each StackOne Integration (aka Provider or Connector) has its own A2A agent and corresponding Agent Card with all skills available to view at a URL like https://a2a.stackone.com/hibob/agent-card.json.

​
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:
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": {
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "List the first 10 employees"
          }
        ]
      },
      "configuration": {
        "blocking": true
      }
    }
  }'
Expected Response:
{
  "jsonrpc": "2.0",
  "id": "msg-1",
  "result": {
    "id": "task-123",
    "contextId": "ctx-456",
    "status": "completed",
    "artifacts": [
      {
        "id": "artifact-1",
        "kind": "text",
        "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",
    "status": "completed",
    "artifacts": [
      {
        "id": "artifact-1",
        "kind": "text",
        "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:

SDK Guides

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)