kubeswarm Agent-to-Agent (A2A) Connections

kubeswarm agents can call other agents as tools during inference via the spec.agents[] section. This enables agent-to-agent collaboration on Kubernetes without pipeline wiring.

How It Works

spec:
  agents:
    - name: researcher
      agentRef:
        name: research-agent     # SwarmAgent in same namespace
      trust: internal
      instructions: "Use for all web research tasks."
    - name: search
      capabilityRef:
        name: code-search        # resolved from SwarmRegistry
      trust: internal

When the agent's LLM decides to call researcher, kubeswarm routes the call through the MCP gateway to the target agent's exposed capabilities.

agentRef vs capabilityRef

Field	Resolves to	Use when
agentRef	A specific SwarmAgent by name	You know which agent to call
capabilityRef	Any agent with that capability in SwarmRegistry	You want registry-based discovery

Exactly one must be set (enforced by CEL validation).

Trust Levels

Each connection has a trust field that controls runtime behavior:

Level	Meaning
internal	Same organization/cluster - baseline behavior
external	Third-party - restricted
sandbox	Untrusted/experimental - strictest validation

The default trust level is set via spec.guardrails.tools.trust.default.

Instructions

The instructions field injects operational context into the agent's system prompt for that specific connection. Use it to scope how the connection should be used:

instructions: "Only use for PR creation. Never use for branch deletion."