Skip to main content

A2A API Reference

Complete reference for Intugle's A2A protocol implementation.

Endpoints​

EndpointMethodAuthDescription
/.well-known/agent-card.jsonGETNoAgent discovery
/POSTYesSend messages (JSON-RPC)

Request Reference​

Headers​

HeaderRequiredDescription
AuthorizationYesBearer <JWT_TOKEN>
Content-TypeYesapplication/json
AcceptRecommendedtext/event-stream for streaming
x-extra-paramsNoJSON object with extra parameters
x-cache-payloadNoCache configuration

x-extra-params Format​

{
  "custom_key": "custom_value"
}

x-cache-payload Format​

{
  "deterministic_cache": true,
  "cache_id": "optional-cache-key"
}

JWT Token Claims​

ClaimRequiredDescription
subscription_idYesYour subscription ID
subscription_uuidYesYour subscription UUID
user_idYesYour user ID
chatapp_idNoChatApp ID or "latest"
expYesExpiration timestamp

Example Token Payload:

{
  "subscription_id": 123,
  "subscription_uuid": "uuid-string",
  "user_id": 456,
  "chatapp_id": "latest",
  "exp": 1234567890
}

Message Format​

Send Message Request​

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "message": {
      "message_id": "unique-id",
      "context_id": "session-id",
      "task_id": "existing-task-id",
      "role": "user",
      "parts": [
        {
          "text": "Your question here",
          "media_type": "text/plain"
        }
      ]
    }
  },
  "id": "request-id"
}

Message Fields​

FieldTypeRequiredDescription
message_idstringYesUnique message identifier
context_idstringNoSession/conversation ID for context continuity
task_idstringNoExisting task ID (for input responses)
rolestringYesMust be "user"
partsarrayYesMessage content parts

Message Part Fields​

FieldTypeRequiredDescription
textstringYesThe message text
media_typestringYes"text/plain" or "application/json"

Supported Media Types: text/plain, application/json

Response Reference​

Streaming Events​

Responses are Server-Sent Events (SSE):

data: {"type": "event_type", ...}

Event Types​

EventDescription
task.createdTask created
task.updatedTask state changed
message.updatedMessage content updated
artifact.updatedArtifact (output) updated

Task States​

StateDescription
submittedTask received, queued
workingProcessing in progress
input_requiredWaiting for user input
completedFinished successfully
failedError occurred
canceledUser canceled

Output Artifacts​

Artifact Structure​

{
  "type": "artifact.updated",
  "artifact": {
    "parts": [
      {
        "text": "Human-readable text",
        "media_type": "text/plain",
        "metadata": {
          "ui_components": [...],
          "execution_time": 2.5,
          "cache": "full",
          "cache_id": "abc123"
        }
      }
    ]
  }
}

UI Component Structure​

Each component in ui_components:

{
  "index": 1,
  "type": "markdown",
  "content": "...",
  "status": "completed",
  "parentid": null
}
FieldTypeDescription
indexnumberComponent order
typestring"markdown", "table", "chart", "card"
contentstring|objectContent (varies by type)
statusstring"partial", "completed", "failed"
parentidstring|nullParent component ID

Markdown Component​

{
  "type": "markdown",
  "content": "## Title\n\nFormatted **text**",
  "status": "completed"
}

Table Component​

{
  "type": "table",
  "content": {
    "data": {
      "columns": ["Customer", "Revenue"],
      "rows": [["Acme", 150000]]
    },
    "title": "Top Customers",
    "column_mappings": {},
    "allow_publish": false
  },
  "status": "completed"
}

Chart Component​

{
  "type": "chart",
  "content": {
    "chart_json": "{ vega-lite spec }",
    "title": "Revenue Trend",
    "chart_type": "line",
    "sample_data": {}
  },
  "status": "completed"
}

Card Component​

{
  "type": "card",
  "content": {
    "title": "Total Revenue",
    "description": "$1.2M",
    "icon": "dollar",
    "right_content": "+15%",
    "right_icon": "arrow-up"
  },
  "status": "completed"
}

Step/Action Events​

Processing steps are sent as status updates:

{
  "type": "task.updated",
  "task": {
    "state": "working"
  },
  "message": {
    "parts": [{
      "data": {
        "id": "step-1",
        "name": "Generating SQL",
        "tool_name": "generate_sql_query",
        "msg": "Building query...",
        "status": "completed",
        "type": "step",
        "ts": 1234567890.123
      },
      "media_type": "application/json"
    }]
  }
}

Step Fields​

FieldTypeDescription
idstringStep identifier
namestringStep name
tool_namestringTool being used (e.g., generate_sql_query, execute_query)
msgstringStatus message
statusstring"partial", "completed", "failed"
typestring"step" or "action"
tsnumberTimestamp
resultobjectStep result data

Input Required (Elicitation)​

When the agent needs input, it sends:

{
  "type": "task.updated",
  "task": {
    "state": "input_required"
  },
  "message": {
    "parts": [{
      "data": {
        "id": "CalculatedField",
        "name": "Define Calculation",
        "msg": "Please provide the formula for profit margin",
        "response_title": "Calculated Field",
        "response_description": "Enter the calculation logic",
        "default_response": "revenue - cost"
      },
      "media_type": "application/json"
    }]
  }
}

Interrupt Types​

TypeDescription
CalculatedFieldDefine a computed column
MetadataEditorEdit metadata definitions

Responding to Input Requests​

Send a follow-up message with the same task_id:

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "message": {
      "message_id": "response-001",
      "task_id": "task-123",
      "role": "user",
      "parts": [{
        "text": "revenue - cost",
        "media_type": "text/plain"
      }]
    }
  },
  "id": "2"
}

Agent Card​

Discover agent capabilities:

GET /.well-known/agent-card.json

Response:

{
  "name": "Intugle Data Agent",
  "description": "Agent for building data apps...",
  "version": "0.1.0",
  "supported_interfaces": [
    {
      "protocol_binding": "JSONRPC",
      "protocol_version": "1.0",
      "url": "https://your-instance.intugle.ai/a2a/"
    }
  ],
  "capabilities": {
    "streaming": true,
    "push_notifications": false
  },
  "security_schemes": {
    "bearerAuth": {
      "http_auth_security_scheme": {
        "scheme": "bearer",
        "bearer_format": "JWT"
      }
    }
  },
  "default_input_modes": ["text/plain", "application/json"],
  "default_output_modes": ["text/plain", "application/json"],
  "skills": [{
    "id": "intugle_data_agent",
    "name": "Intugle Data Agent",
    "description": "...",
    "tags": ["data", "analytics", "metadata", "agent"],
    "examples": [
      "Show me customer growth over time",
      "Find tables related to revenue",
      "Build a chart for monthly sales"
    ]
  }]
}

Cancel Task​

{
  "jsonrpc": "2.0",
  "method": "task/cancel",
  "params": {
    "task_id": "task-123"
  },
  "id": "3"
}

Error Handling​

JSON-RPC Errors​

CodeMessage
-32700Parse error
-32600Invalid request
-32601Method not found
-32602Invalid params

Application Errors​

HTTPDescription
401Invalid/expired token
403No access to workspace
408Request timeout

Configuration Reference​

SettingDefaultDescription
A2A_AGENT_NAMEIntugle AgentAgent name in card
A2A_AGENT_VERSION0.1.0Agent version
A2A_CLIENT_DISCONNECT_TIMEOUT_MS15000Disconnect timeout