Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
A2A Protocol (Agent-to-Agent)

The A2A Protocol implements Google’s Agent-to-Agent interoperability standard. It allows external AI agents to discover your thinnestAI agents and invoke them programmatically — enabling cross-platform agent collaboration.

​
What is A2A?

A2A (Agent-to-Agent) is an open protocol that defines how AI agents communicate with each other. It provides:
  • Discovery — Agents publish a machine-readable “agent card” at a well-known URL
  • Invocation — External agents can send messages and receive responses
  • Capabilities — Each agent advertises what it can do via skills and capabilities
Think of it like an API for AI agents — but standardized so any A2A-compatible agent can communicate with any other.

​
Enabling A2A on an Agent

​
From the Dashboard

  1. Go to your agent’s settings.
  2. Open the A2A tab.
  3. Toggle Enable A2A Protocol.
  4. Configure:
    • Capabilities — What the agent can do (e.g., text-generation, data-lookup)
    • Skills — Named abilities with descriptions
  5. Save.

​
Via Agent Configuration

A2A is configured in the agent’s config.a2a object: 
{
  "a2a": {
    "enabled": true,
    "capabilities": ["text-generation", "knowledge-search"],
    "skills": [
      {
        "id": "customer-support",
        "name": "Customer Support",
        "description": "Answer customer questions about products, orders, and returns"
      },
      {
        "id": "order-lookup",
        "name": "Order Lookup",
        "description": "Look up order status by order number or customer email"
      }
    ]
  }
}

​
Agent Discovery

Once A2A is enabled, your agent publishes an agent card at a well-known URL: 
GET https://api.thinnest.ai/a2a/agents/{agent_id}/.well-known/agent.json

​
Agent Card Response

{
  "name": "Customer Support Agent",
  "description": "Answer customer questions about products, orders, and returns",
  "url": "https://api.thinnest.ai/a2a/agents/agent_abc123/invoke",
  "version": "1.0",
  "capabilities": ["text-generation", "knowledge-search"],
  "skills": [
    {
      "id": "customer-support",
      "name": "Customer Support",
      "description": "Answer customer questions about products, orders, and returns"
    },
    {
      "id": "order-lookup",
      "name": "Order Lookup",
      "description": "Look up order status by order number or customer email"
    }
  ]
}
External agents use this card to understand what your agent can do and how to invoke it.

​
Invoking an Agent via A2A

External agents send messages using the invoke endpoint: 
curl -X POST https://api.thinnest.ai/a2a/agents/agent_abc123/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "role": "user",
      "content": "What is the status of order #12345?"
    },
    "session_id": "a2a_session_001",
    "skill_id": "order-lookup"
  }'

​
Response

{
  "id": "msg_a2a_xyz",
  "message": {
    "role": "assistant",
    "content": "Order #12345 is currently in transit. It was shipped on March 4 and is expected to arrive by March 8. The tracking number is 1Z999AA10123456784."
  },
  "metadata": {
    "agent_name": "Customer Support Agent",
    "model": "gpt-4o",
    "tokens_used": 245
  }
}

​
Architecture

External Agent                    thinnestAI
     │
     │  GET /.well-known/agent.json
     │──────────────────────────────→│  Agent Card
     │←──────────────────────────────│  (capabilities, skills)
     │
     │  POST /invoke
     │──────────────────────────────→│  Process message
     │                               │  ├── Load agent config
     │                               │  ├── Run through LLM
     │                               │  ├── Execute tools
     │                               │  └── Check billing
     │←──────────────────────────────│  Return response
     │

​
Billing

A2A invocations consume tokens from the agent owner’s account, not the calling agent’s. Token usage is tracked per invocation and charged at the same rate as regular agent usage. The system checks the agent owner’s balance before processing. If insufficient, the invocation returns a 402 Payment Required error.

​
Security

  • A2A endpoints are public by design (for interoperability), but invocations are tracked and billed
  • Rate limiting applies to prevent abuse
  • The agent card only exposes the agent name, description, and capabilities — not internal configuration
  • Session IDs allow maintaining conversation context across multiple invocations

​
Use Cases

​
Cross-Platform Agent Collaboration

An external scheduling agent discovers your support agent and delegates customer queries: 
Scheduling Agent → "I have a customer asking about a refund. Can you help?"
                 → A2A invoke to your support agent
                 ← "The refund has been processed. The customer should see it in 3-5 business days."

​
Agent Marketplaces

Publish your agents to A2A-compatible marketplaces where other organizations can discover and use them.

​
Internal Agent Networks

Build a network of specialized agents within your organization that can call each other: 
Router Agent → discovers available agents
             → invokes the best-fit agent for each request
             → aggregates responses

​
Best Practices

  • Write clear skill descriptions — External agents use these to decide whether to invoke your agent.
  • Keep capabilities accurate — Don’t advertise capabilities your agent doesn’t have.
  • Monitor A2A usage — Track invocations in your analytics to understand external demand.
  • Set billing alerts — A2A invocations consume your tokens, so monitor usage.
  • Use session IDs — Maintain context across multi-turn A2A conversations.