A2A Services

A2A (Agent-to-Agent) services let your formation communicate with external agent systems. Define connections to remote services that your agents can delegate tasks to.

Your First A2A Service

Create a2a/analytics.afs:

schema: "1.0.0"
id: analytics-engine
name: Analytics Engine
description: External analytics service for data processing

endpoint: "https://analytics.company.com"
auth:
  type: bearer
  token: "${{ secrets.ANALYTICS_TOKEN }}"

Configuration Fields

Required Fields

Connection Settings

Retry Configuration

retry_attempts: 3
retry_delay_seconds: 1
retry_backoff_multiplier: 2.0

Authentication

Bearer Token

auth:
  type: bearer
  token: "${{ secrets.SERVICE_TOKEN }}"

Basic Auth

auth:
  type: basic
  username: "${{ secrets.SERVICE_USERNAME }}"
  password: "${{ secrets.SERVICE_PASSWORD }}"

API Key

auth:
  type: api_key
  header: "X-API-Key"
  key: "${{ secrets.SERVICE_API_KEY }}"

OAuth2

auth:
  type: oauth2
  oauth2:
    client_id: "your-client-id"
    client_secret: "${{ secrets.OAUTH_SECRET }}"
    token_url: "https://auth.example.com/oauth/token"
    scopes: ["read", "write"]

Health Checks

Monitor service availability:

health_check:
  enabled: true
  endpoint: "/health"
  interval_seconds: 60
  timeout_seconds: 5
  unhealthy_threshold: 3   # Failures before marking unhealthy
  healthy_threshold: 2     # Successes before marking healthy

Circuit Breaker

Prevent cascade failures:

circuit_breaker:
  enabled: true
  failure_threshold: 5     # Failures before opening circuit
  success_threshold: 2     # Successes before closing circuit
  timeout_seconds: 60      # Time in open state before retry

Rate Limiting

Control request rates:

rate_limiting:
  requests_per_second: 10
  requests_per_minute: 100
  requests_per_hour: 1000
  requests_per_day: 10000
  burst_limit: 20
  strategy: "sliding_window"  # sliding_window, fixed_window, token_bucket

Capabilities

Describe what the service offers:

capabilities:
  agents: ["analytics-agent", "reporting-agent"]
  features: ["data-analysis", "visualization"]
  streaming: true
  async: true
  webhooks: true

Service Discovery

Routing and load balancing:

discovery:
  registry_url: "https://registry.example.com"
  tags: ["analytics", "data", "reporting"]
  priority: 10      # Higher = higher priority
  weight: 100       # 0-100 for load balancing

Metadata

Additional service information:

metadata:
  owner: "Data Team"
  contact: "data-team@company.com"
  documentation: "https://docs.analytics.company.com"
  environment: "production"  # development, staging, production
  sla:
    uptime_percentage: 99.9
    response_time_ms: 500

Full Example

# a2a/analytics-engine.afs
schema: "1.0.0"
id: analytics-engine
name: Analytics Engine
description: External analytics for data processing and visualization

endpoint: "https://analytics.company.com"
protocol: https
version: "2.1.0"
timeout_seconds: 60

auth:
  type: bearer
  token: "${{ secrets.ANALYTICS_TOKEN }}"

retry_attempts: 3
retry_delay_seconds: 1
retry_backoff_multiplier: 2.0

health_check:
  enabled: true
  endpoint: "/health"
  interval_seconds: 60

circuit_breaker:
  enabled: true
  failure_threshold: 5
  timeout_seconds: 60

rate_limiting:
  requests_per_minute: 100
  burst_limit: 20

capabilities:
  agents: ["data-analyst", "report-generator"]
  features: ["analysis", "visualization", "export"]
  streaming: true
  async: true

metadata:
  owner: "Data Team"
  documentation: "https://docs.analytics.company.com"
  environment: "production"

Learn More

• Agents Reference - Configure agent delegation
• Tools Reference - MCP tool integration
• Secrets Reference - Managing service credentials