@bluefly/openstandardagents 0.3.5 → 0.4.0

package/spec/v0.4/extensions/a2a/README.md

@@ -0,0 +1,193 @@
+# A2A (Agent-to-Agent) Communication Extension
+
+**Version**: 0.3.5
+**Status**: Stable
+**Protocol**: Production-Ready A2A
+
+## Overview
+
+The A2A extension enables production-ready agent-to-agent communication with service discovery, message routing, task delegation, completion signals, and checkpoint synchronization.
+
+## Features
+
+- **Service Discovery**: DNS, Consul, Kubernetes, Registry-based discovery
+- **Message Routing**: Direct, broadcast, round-robin, capability-based routing
+- **Task Delegation**: Multi-level delegation with handoff support
+- **Completion Signals**: Standardized task completion signaling
+- **Checkpoint Sync**: Distributed checkpoint synchronization
+- **Authentication**: mTLS, OAuth2, API Key, JWT support
+- **Resilience**: Retry policies, circuit breakers, health checks
+- **Observability**: Distributed tracing, metrics, logging
+
+## Schema Reference
+
+### Basic A2A Configuration
+
+```yaml
+extensions:
+  a2a:
+    enabled: true
+    protocol:
+      type: json-rpc
+      version: "2.0"
+      messageFormat: json
+      timeout: 30
+    endpoints:
+      - agentId: "@security-scanner"
+        url: "http://security-scanner:8080/a2a"
+        capabilities: ["security-scan", "vulnerability-check"]
+        priority: 10
+```
+
+### Service Discovery
+
+```yaml
+extensions:
+  a2a:
+    discovery:
+      enabled: true
+      mechanism: registry
+      registryUrl: "https://registry.example.com/agents"
+      refreshInterval: 60
+      healthCheck:
+        enabled: true
+        interval: 30
+        timeout: 5
+        endpoint: "/health"
+```
+
+### Routing Configuration
+
+```yaml
+extensions:
+  a2a:
+    routing:
+      strategy: capability-based
+      defaultAgent: "@fallback-agent"
+      routingRules:
+        - name: "security-routing"
+          condition: "message.type == 'security-scan'"
+          target: "@security-scanner"
+          priority: 10
+        - name: "code-review-routing"
+          condition: "message.type == 'code-review'"
+          target: "@mr-reviewer"
+          priority: 5
+```
+
+### Task Delegation
+
+```yaml
+extensions:
+  a2a:
+    delegation:
+      enabled: true
+      maxDepth: 3
+      timeout: 300
+      handoff:
+        enabled: true
+        preserveContext: true
+        handoffRules:
+          - name: "escalation"
+            condition: "signal == 'escalate'"
+            target: "@senior-reviewer"
+            message: "Escalating to senior reviewer"
+```
+
+### Completion Signals
+
+```yaml
+extensions:
+  a2a:
+    completionSignals:
+      enabled: true
+      signals: ["continue", "complete", "blocked", "escalate", "checkpoint"]
+      handlers:
+        - signal: escalate
+          action: handoff
+          target: "@senior-agent"
+        - signal: checkpoint
+          action: checkpoint
+          config:
+            storage: agent-brain
+```
+
+### Authentication
+
+```yaml
+extensions:
+  a2a:
+    authentication:
+      type: mtls
+      mtls:
+        certPath: "/certs/client.crt"
+        keyPath: "/certs/client.key"
+        caPath: "/certs/ca.crt"
+        verifyPeer: true
+```
+
+## Use Cases
+
+### 1. Multi-Agent Code Review System
+
+```yaml
+apiVersion: ossa/v0.3.5
+kind: Agent
+metadata:
+  name: mr-coordinator
+spec:
+  extensions:
+    a2a:
+      enabled: true
+      protocol:
+        type: json-rpc
+        version: "2.0"
+      endpoints:
+        - agentId: "@security-scanner"
+          url: "http://security-scanner:8080/a2a"
+          capabilities: ["security-scan"]
+        - agentId: "@performance-analyzer"
+          url: "http://performance-analyzer:8080/a2a"
+          capabilities: ["performance-analysis"]
+      routing:
+        strategy: capability-based
+      delegation:
+        enabled: true
+        maxDepth: 2
+```
+
+### 2. Service Discovery with Kubernetes
+
+```yaml
+apiVersion: ossa/v0.3.5
+kind: Agent
+metadata:
+  name: distributed-agent
+spec:
+  extensions:
+    a2a:
+      enabled: true
+      discovery:
+        enabled: true
+        mechanism: kubernetes
+        refreshInterval: 60
+      protocol:
+        type: grpc
+        version: "1.0"
+```
+
+## Best Practices
+
+1. **Service Discovery**: Use registry or Kubernetes for dynamic environments
+2. **Authentication**: Always use mTLS or OAuth2 in production
+3. **Circuit Breakers**: Enable to prevent cascading failures
+4. **Health Checks**: Configure for automatic unhealthy agent removal
+5. **Delegation Depth**: Keep maxDepth <= 3 to avoid deep chains
+6. **Timeouts**: Set appropriate timeouts for agent response times
+7. **Observability**: Enable tracing for debugging distributed workflows
+
+## References
+
+- [OSSA v0.3.5 Specification](../../README.md)
+- [MCP Extension](../mcp/README.md)
+- [Kagent Extension](../kagent/README.md)

package/spec/v0.4/extensions/a2a/a2a.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openstandardagents.org/schemas/v0.3.5/extensions/a2a.json",
+  "title": "A2A Extension Schema",
+  "description": "Agent-to-Agent communication extension for OSSA",
+  "type": "object",
+  "properties": {
+    "service_discovery": {
+      "type": "object",
+      "description": "Service discovery configuration",
+      "properties": {
+        "enabled": { "type": "boolean", "default": true },
+        "registry_url": { "type": "string", "format": "uri" },
+        "health_check_interval": { "type": "integer", "minimum": 0 },
+        "timeout": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "agent_card": {
+      "type": "object",
+      "description": "Agent identity card for A2A",
+      "properties": {
+        "agent_uri": { "type": "string", "pattern": "^agent://" },
+        "capabilities": { "type": "array", "items": { "type": "string" } },
+        "protocols": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["json-rpc", "grpc", "http", "websocket"]
+          }
+        },
+        "endpoints": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "url": { "type": "string", "format": "uri" },
+              "protocol": { "type": "string" },
+              "auth_required": { "type": "boolean" }
+            }
+          }
+        }
+      },
+      "required": ["agent_uri", "capabilities"]
+    },
+    "handoff_protocol": {
+      "type": "object",
+      "description": "Task handoff configuration",
+      "properties": {
+        "strategy": {
+          "type": "string",
+          "enum": ["capability_match", "load_balance", "round_robin", "custom"]
+        },
+        "timeout": { "type": "integer" },
+        "retry_policy": {
+          "type": "object",
+          "properties": {
+            "max_retries": { "type": "integer" },
+            "backoff_ms": { "type": "integer" }
+          }
+        }
+      }
+    },
+    "auth": {
+      "type": "object",
+      "description": "Authentication configuration",
+      "properties": {
+        "method": {
+          "type": "string",
+          "enum": ["jwt", "oauth2", "api_key", "mtls"]
+        },
+        "issuer": { "type": "string" },
+        "audience": { "type": "string" }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/spec/v0.4/extensions/ag2/ag2.schema.json

@@ -0,0 +1,277 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openstandardagents.org/schemas/v0.3.5/extensions/ag2/ag2.json",
+  "title": "AG2 (AutoGen) Extension",
+  "description": "Native integration with Microsoft AG2 (AutoGen) for multi-agent conversations, group chats, nested chats, and swarm topologies.",
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "default": true,
+      "description": "Enable AG2 integration"
+    },
+    "pattern": {
+      "type": "string",
+      "enum": ["group_chat", "nested_chat", "swarm", "sequential", "two_agent"],
+      "description": "AG2 conversation pattern"
+    },
+    "group_chat": {
+      "$ref": "#/definitions/GroupChatConfig",
+      "description": "Group chat configuration"
+    },
+    "nested_chat": {
+      "$ref": "#/definitions/NestedChatConfig",
+      "description": "Nested chat configuration"
+    },
+    "swarm": {
+      "$ref": "#/definitions/SwarmConfig",
+      "description": "Swarm topology configuration"
+    },
+    "code_execution": {
+      "$ref": "#/definitions/CodeExecutionConfig",
+      "description": "Code execution configuration"
+    },
+    "human_input_mode": {
+      "type": "string",
+      "enum": ["ALWAYS", "NEVER", "TERMINATE"],
+      "default": "NEVER",
+      "description": "When to request human input"
+    },
+    "max_consecutive_auto_reply": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Maximum consecutive auto-replies"
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "GroupChatConfig": {
+      "type": "object",
+      "description": "Group chat configuration",
+      "required": ["participants", "manager"],
+      "properties": {
+        "participants": {
+          "type": "array",
+          "minItems": 2,
+          "items": {
+            "type": "string",
+            "pattern": "^@[a-z0-9-]+$"
+          },
+          "description": "Agent IDs participating in group chat"
+        },
+        "manager": {
+          "type": "string",
+          "pattern": "^@[a-z0-9-]+$",
+          "description": "Group chat manager agent ID"
+        },
+        "max_round": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100,
+          "default": 10,
+          "description": "Maximum conversation rounds"
+        },
+        "speaker_selection_method": {
+          "type": "string",
+          "enum": ["auto", "manual", "round_robin", "random"],
+          "default": "auto",
+          "description": "Speaker selection method"
+        },
+        "allow_repeat_speaker": {
+          "type": "boolean",
+          "default": true,
+          "description": "Allow same agent to speak consecutively"
+        },
+        "transitions": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "description": "Allowed speaker transitions"
+        },
+        "enable_clear_history": {
+          "type": "boolean",
+          "default": false,
+          "description": "Allow clearing conversation history"
+        }
+      },
+      "additionalProperties": false
+    },
+    "NestedChatConfig": {
+      "type": "object",
+      "description": "Nested chat configuration",
+      "required": ["triggers"],
+      "properties": {
+        "triggers": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/NestedChatTrigger"
+          },
+          "description": "Nested chat triggers"
+        },
+        "max_depth": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 3,
+          "description": "Maximum nesting depth"
+        }
+      },
+      "additionalProperties": false
+    },
+    "NestedChatTrigger": {
+      "type": "object",
+      "description": "Nested chat trigger",
+      "required": ["condition", "chat_queue"],
+      "properties": {
+        "condition": {
+          "type": "string",
+          "description": "Trigger condition (function or expression)"
+        },
+        "chat_queue": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["recipient", "message"],
+            "properties": {
+              "recipient": {
+                "type": "string",
+                "pattern": "^@[a-z0-9-]+$",
+                "description": "Recipient agent ID"
+              },
+              "message": {
+                "type": "string",
+                "description": "Message to send"
+              },
+              "summary_method": {
+                "type": "string",
+                "enum": ["last_msg", "reflection_with_llm"],
+                "default": "last_msg"
+              }
+            }
+          },
+          "description": "Chat queue for nested conversation"
+        }
+      },
+      "additionalProperties": false
+    },
+    "SwarmConfig": {
+      "type": "object",
+      "description": "Swarm topology configuration",
+      "required": ["agents", "handoffs"],
+      "properties": {
+        "agents": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/SwarmAgent"
+          },
+          "description": "Swarm agents"
+        },
+        "handoffs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/SwarmHandoff"
+          },
+          "description": "Agent handoff rules"
+        },
+        "update_agent_state_before_reply": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          },
+          "description": "State update functions"
+        }
+      },
+      "additionalProperties": false
+    },
+    "SwarmAgent": {
+      "type": "object",
+      "description": "Swarm agent definition",
+      "required": ["id", "name"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^@[a-z0-9-]+$",
+          "description": "Agent ID"
+        },
+        "name": {
+          "type": "string",
+          "description": "Agent name"
+        },
+        "system_message": {
+          "type": "string",
+          "description": "Agent system message"
+        },
+        "functions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Available functions"
+        }
+      },
+      "additionalProperties": false
+    },
+    "SwarmHandoff": {
+      "type": "object",
+      "description": "Swarm handoff rule",
+      "required": ["from", "to", "condition"],
+      "properties": {
+        "from": {
+          "type": "string",
+          "pattern": "^@[a-z0-9-]+$",
+          "description": "Source agent ID"
+        },
+        "to": {
+          "type": "string",
+          "pattern": "^@[a-z0-9-]+$",
+          "description": "Target agent ID"
+        },
+        "condition": {
+          "type": "string",
+          "description": "Handoff condition"
+        },
+        "available": {
+          "type": "string",
+          "description": "Availability condition"
+        }
+      },
+      "additionalProperties": false
+    },
+    "CodeExecutionConfig": {
+      "type": "object",
+      "description": "Code execution configuration",
+      "properties": {
+        "work_dir": {
+          "type": "string",
+          "description": "Working directory for code execution"
+        },
+        "use_docker": {
+          "oneOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "string"
+            }
+          ],
+          "description": "Use Docker for code execution (bool or image name)"
+        },
+        "timeout": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 60,
+          "description": "Code execution timeout in seconds"
+        },
+        "last_n_messages": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Number of recent messages to include in code execution context"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}