Agent Network Best Practices

general > protocol-version-validation

Guidance

This rule validates that agent cards use the currently supported A2A (Agent-to-Agent) protocol version family, which is 0.3.X. Protocol versions define the communication contract between agents, including message formats, capability negotiations, and interaction patterns. Unsupported protocol versions lead to compatibility issues where agents can't properly communicate, feature mismatches where expected capabilities are unavailable or behave differently, and potential security vulnerabilities if older versions lack important security improvements. Keeping within the supported protocol version range helps agents reliably interoperate within the network and get the latest protocol features and security improvements. This rule applies to all agent cards in broker definitions and external agent declarations across Agent Network specifications. It maintains protocol compatibility and consistency throughout the agent ecosystem.

Message

A2A protocol version must be the latest supported version (0.3.X). Using older or newer versions may lead to compatibility issues and security vulnerabilities.

Examples

valid

schemaVersion: 1.0.0
brokers:
  my-broker:
    card:
      protocolVersion: "0.3.0"
      name: "My Broker"
      description: "A sample broker with latest supported protocol version"
      url: "https://my-broker.example.com"
      provider:
        organization: "Example Corp"
        url: "https://example.com"
      defaultInputModes:
        - "application/json"
      defaultOutputModes:
        - "application/json"
      skills:
        - id: "coordination"
          name: "Agent Coordination"
          description: "Coordinates agent activities"
          tags: ["coordination", "orchestration"]
      capabilities:
        streaming: false
        pushNotifications: false
        stateTransitionHistory: false
        extensions: []
      version: "1.0.0"
    spec:
      llmRef:
        name: my-openai
      instructions:
        - "You are a helpful assistant that coordinates agent activities"
      maxNumberOfLoops: 25
      maxConsecutiveErrors: 3
      links:
        - agentRef:
            name: external-agent
llms:
  my-openai:
    kind: openai
    description: "OpenAI GPT-4 model for reasoning"

invalid_older

schemaVersion: 1.0.0
brokers:
  my-broker:
    card:
      protocolVersion: "0.2.5"
      name: "My Broker"
      description: "A sample broker with older protocol version"
      url: "https://my-broker.example.com"
      provider:
        organization: "Example Corp"
        url: "https://example.com"
      defaultInputModes:
        - "application/json"
      defaultOutputModes:
        - "application/json"
      skills:
        - id: "coordination"
          name: "Agent Coordination"
          description: "Coordinates agent activities"
          tags: ["coordination", "orchestration"]
      capabilities:
        streaming: false
        pushNotifications: false
        stateTransitionHistory: false
        extensions: []
      version: "1.0.0"
    spec:
      llmRef:
        name: my-openai
      instructions:
        - "You are a helpful assistant that coordinates agent activities"
      maxNumberOfLoops: 25
      maxConsecutiveErrors: 3
      links:
        - agentRef:
            name: external-agent
llms:
  my-openai:
    kind: openai
    description: "OpenAI GPT-4 model for reasoning"

invalid_newer

schemaVersion: 1.0.0
brokers:
  my-broker:
    card:
      protocolVersion: "0.4.0"
      name: "My Broker"
      description: "A sample broker with newer unsupported protocol version"
      url: "https://my-broker.example.com"
      provider:
        organization: "Example Corp"
        url: "https://example.com"
      defaultInputModes:
        - "application/json"
      defaultOutputModes:
        - "application/json"
      skills:
        - id: "coordination"
          name: "Agent Coordination"
          description: "Coordinates agent activities"
          tags: ["coordination", "orchestration"]
      capabilities:
        streaming: false
        pushNotifications: false
        stateTransitionHistory: false
        extensions: []
      version: "1.0.0"
    spec:
      llmRef:
        name: my-openai
      instructions:
        - "You are a helpful assistant that coordinates agent activities"
      maxNumberOfLoops: 25
      maxConsecutiveErrors: 3
      links:
        - agentRef:
            name: external-agent
llms:
  my-openai:
    kind: openai
    description: "OpenAI GPT-4 model for reasoning"

Applies to card

Constraint

Type: Declarative Validation