# DEVELOPER GUIDE: a2a_spec

## Quick Summary
The `a2a_spec` directory contains the complete Agent-to-Agent (A2A) communication specification for the Solace Agent Mesh. It includes the main JSON schema definition (`a2a.json`) that defines all data structures, request/response types, and error codes for agent communication, plus a `schemas/` subdirectory containing specialized validation schemas for various agent signals and progress updates. Together, these provide a comprehensive framework for validating and implementing compliant agent-to-agent communication.

## Files and Subdirectories Overview
- **Direct files:**
  - `a2a.json` - Complete JSON Schema specification for A2A protocol including all data types, requests, responses, and error definitions
  - `a2a_spec_llm.txt` - Developer guide documentation for the A2A specification
- **Subdirectories:**
  - `schemas/` - JSON Schema definitions for agent communication signals (progress updates, tool invocations, LLM calls, artifact creation)

## Developer API Reference

### Direct Files

#### a2a.json
**Purpose:** Complete JSON Schema specification defining the Agent-to-Agent communication protocol
**Import:** This is a JSON Schema file, typically loaded for validation purposes

**Key Schema Definitions:**
- **AgentCard** - Self-describing manifest for agents with capabilities, skills, and endpoints
- **Message** - Individual messages in agent conversations with parts (text, files, data)
- **Task** - Stateful operations/conversations between clients and agents
- **A2ARequest/A2AResponse** - All supported JSON-RPC request and response types
- **Security Schemes** - OAuth2, API Key, mTLS, and other authentication methods
- **Error Types** - Standard JSON-RPC and A2A-specific error definitions

**Core Data Structures:**
```typescript
// Agent Card - describes agent capabilities
AgentCard {
  name: string
  description: string
  url: string
  skills: AgentSkill[]
  capabilities: AgentCapabilities
  security: SecurityRequirement[]
  // ... additional fields
}

// Message - conversation content
Message {
  messageId: string
  role: "user" | "agent"
  parts: Part[] // TextPart | FilePart | DataPart
  taskId?: string
  contextId?: string
}

// Task - stateful operation
Task {
  id: string
  contextId: string
  status: TaskStatus
  history?: Message[]
  artifacts?: Artifact[]
}
```

#### a2a_spec_llm.txt
**Purpose:** Developer documentation and usage guide for the A2A specification
**Import:** Documentation file for reference

### Subdirectory APIs

#### schemas/
**Purpose:** Provides JSON Schema definitions for agent communication signals and progress updates
**Key Exports:** Schema definitions for progress tracking, tool invocations, LLM calls, and artifact creation
**Import Examples:**
```python
import json
from jsonschema import validate

# Load and use schemas for validation
with open('solace_agent_mesh/common/a2a_spec/schemas/agent_progress_update.json') as f:
    progress_schema = json.load(f)
```

**Available Schemas:**
- `agent_progress_update.json` - General progress status messages
- `artifact_creation_progress.json` - File/artifact creation tracking with chunked data
- `llm_invocation.json` - LLM model invocation signals
- `tool_invocation_start.json` - Tool execution start notifications
- `tool_result.json` - Tool execution completion results

## Complete Usage Guide

### 1. Loading and Using the A2A Schema

```python
import json
from jsonschema import validate, Draft7Validator

# Load the main A2A schema
with open('solace_agent_mesh/common/a2a_spec/a2a.json') as f:
    a2a_schema = json.load(f)

# Create validator for specific types
def validate_agent_card(card_data):
    """Validate an AgentCard against the schema"""
    card_schema = a2a_schema['definitions']['AgentCard']
    validate(instance=card_data, schema=card_schema)

def validate_message(message_data):
    """Validate a Message against the schema"""
    message_schema = a2a_schema['definitions']['Message']
    validate(instance=message_data, schema=message_schema)

def validate_request(request_data):
    """Validate an A2A request"""
    request_schema = a2a_schema['definitions']['A2ARequest']
    validate(instance=request_data, schema=request_schema)
```

### 2. Creating Valid A2A Data Structures

```python
# Create a valid Message
message = {
    "kind": "message",
    "messageId": "msg-123",
    "role": "user",
    "parts": [
        {
            "kind": "text",
            "text": "Hello, can you help me with a task?"
        }
    ]
}

# Create a SendMessage request
send_request = {
    "jsonrpc": "2.0",
    "id": "req-456",
    "method": "message/send",
    "params": {
        "message": message
    }
}

# Validate the request
validate_request(send_request)
```

### 3. Using Agent Communication Schemas

```python
import json
from jsonschema import validate

# Load and validate progress update
with open('solace_agent_mesh/common/a2a_spec/schemas/agent_progress_update.json') as f:
    progress_schema = json.load(f)

progress_update = {
    "type": "agent_progress_update",
    "status_text": "Processing your request..."
}
validate(instance=progress_update, schema=progress_schema)

# Load and validate tool invocation
with open('solace_agent_mesh/common/a2a_spec/schemas/tool_invocation_start.json') as f:
    tool_schema = json.load(f)

tool_invocation = {
    "type": "tool_invocation_start",
    "tool_name": "file_reader",
    "tool_args": {"filepath": "/data/file.txt"},
    "function_call_id": "call_123"
}
validate(instance=tool_invocation, schema=tool_schema)

# Load and validate tool result
with open('solace_agent_mesh/common/a2a_spec/schemas/tool_result.json') as f:
    result_schema = json.load(f)

tool_result = {
    "type": "tool_result",
    "tool_name": "file_reader",
    "result_data": {"content": "File contents...", "size": 1024},
    "function_call_id": "call_123"
}
validate(instance=tool_result, schema=result_schema)
```

### 4. Working with Agent Cards

```python
# Create a complete AgentCard
agent_card = {
    "name": "Document Processor",
    "description": "Agent that processes and analyzes documents",
    "url": "https://api.example.com/agent",
    "version": "1.0.0",
    "protocolVersion": "0.3.0",
    "capabilities": {
        "streaming": True,
        "pushNotifications": False,
        "stateTransitionHistory": True
    },
    "defaultInputModes": ["text/plain", "application/pdf"],
    "defaultOutputModes": ["text/plain", "application/json"],
    "skills": [
        {
            "id": "document-analysis",
            "name": "Document Analysis",
            "description": "Analyze and extract information from documents",
            "tags": ["document", "analysis", "extraction"]
        }
    ]
}

# Validate the agent card
validate_agent_card(agent_card)
```

### 5. Artifact Creation Progress Tracking

```python
# Load artifact creation schema
with open('solace_agent_mesh/common/a2a_spec/schemas/artifact_creation_progress.json') as f:
    artifact_schema = json.load(f)

# Track artifact creation with chunked data
artifact_progress = {
    "type": "artifact_creation_progress",
    "filename": "report.pdf",
    "bytes_saved": 1024,
    "artifact_chunk": "JVBERi0xLjQKJcOkw7zDtsO..."  # Base64 encoded chunk
}
validate(instance=artifact_progress, schema=artifact_schema)
```

### 6. LLM Invocation Tracking

```python
# Load LLM invocation schema
with open('solace_agent_mesh/common/a2a_spec/schemas/llm_invocation.json') as f:
    llm_schema = json.load(f)

# Track LLM calls
llm_invocation = {
    "type": "llm_invocation",
    "request": {
        "model": "gpt-4",
        "messages": [{"role": "user", "content": "Analyze this data"}],
        "temperature": 0.7
    }
}
validate(instance=llm_invocation, schema=llm_schema)
```

### 7. Complete Request/Response Flow with Progress Tracking

```python
# 1. Create and send a message
message = {
    "kind": "message",
    "messageId": "msg-001",
    "role": "user",
    "parts": [{"kind": "text", "text": "Analyze this document"}]
}

request = {
    "jsonrpc": "2.0",
    "id": "req-001",
    "method": "message/send",
    "params": {
        "message": message,
        "configuration": {
            "blocking": False,
            "acceptedOutputModes": ["text/plain", "application/json"]
        }
    }
}

# 2. Send progress updates during processing
def send_progress_update(status_text):
    progress = {
        "type": "agent_progress_update",
        "status_text": status_text
    }
    # Validate and send progress update
    validate(instance=progress, schema=progress_schema)
    return progress

# 3. Track tool invocations
def track_tool_invocation(tool_name, args, call_id):
    invocation = {
        "type": "tool_invocation_start",
        "tool_name": tool_name,
        "tool_args": args,
        "function_call_id": call_id
    }
    validate(instance=invocation, schema=tool_schema)
    return invocation

# 4. Track tool results
def track_tool_result(tool_name, result_data, call_id):
    result = {
        "type": "tool_result",
        "tool_name": tool_name,
        "result_data": result_data,
        "function_call_id": call_id
    }
    validate(instance=result, schema=result_schema)
    return result
```

### 8. Comprehensive Schema Validation Utilities

```python
class A2AValidator:
    """Utility class for A2A schema validation"""
    
    def __init__(self, schema_dir='solace_agent_mesh/common/a2a_spec'):
        self.schema_dir = schema_dir
        self.main_schema = self._load_main_schema()
        self.signal_schemas = self._load_signal_schemas()
    
    def _load_main_schema(self):
        with open(f'{self.schema_dir}/a2a.json') as f:
            return json.load(f)
    
    def _load_signal_schemas(self):
        schemas = {}
        schema_files = [
            'agent_progress_update.json',
            'artifact_creation_progress.json',
            'llm_invocation.json',
            'tool_invocation_start.json',
            'tool_result.json'
        ]
        for filename in schema_files:
            with open(f'{self.schema_dir}/schemas/{filename}') as f:
                schema_name = filename.replace('.json', '')
                schemas[schema_name] = json.load(f)
        return schemas
    
    def validate_definition(self, data, definition_name):
        """Validate data against a specific A2A definition"""
        schema = self.main_schema['definitions'][definition_name]
        validate(instance=data, schema=schema)
    
    def validate_signal(self, data, signal_type):
        """Validate agent communication signal"""
        schema = self.signal_schemas[signal_type]
        validate(instance=data, schema=schema)
    
    def validate_a2a_message(self, message_data):
        """Validate a complete A2A message"""
        self.validate_definition(message_data, 'Message')
    
    def validate_agent_card(self, card_data):
        """Validate an agent card"""
        self.validate_definition(card_data, 'AgentCard')
    
    def validate_task(self, task_data):
        """Validate a task object"""
        self.validate_definition(task_data, 'Task')

# Usage example
validator = A2AValidator()

# Validate main A2A objects
validator.validate_agent_card(agent_card)
validator.validate_a2a_message(message)

# Validate communication signals
validator.validate_signal(progress_update, 'agent_progress_update')
validator.validate_signal(tool_invocation, 'tool_invocation_start')
validator.validate_signal(tool_result, 'tool_result')
validator.validate_signal(artifact_progress, 'artifact_creation_progress')
validator.validate_signal(llm_invocation, 'llm_invocation')
```

### 9. Error Handling with A2A Error Types

```python
# Create A2A-specific errors using the schema definitions
task_not_found_error = {
    "code": -32001,
    "message": "Task not found",
    "data": {"taskId": "task-123"}
}

content_type_error = {
    "code": -32005,
    "message": "Incompatible content types",
    "data": {"requested": "image/png", "supported": ["text/plain", "application/json"]}
}

# Create error response
error_response = {
    "jsonrpc": "2.0",
    "id": "req-456",
    "error": task_not_found_error
}

# Validate error response
validator.validate_definition(error_response, 'JSONRPCErrorResponse')
```

This comprehensive guide shows how to use both the main A2A specification and the specialized signal schemas together to build compliant agent-to-agent communication systems in the Solace Agent Mesh, including progress tracking, tool invocation monitoring, LLM call tracking, and artifact creation progress.

# content_hash: f9b143dcd949464f8cf51960be146ae5a87bdd25fd2af5cd93c400925212bb24
