Agent Network Best Practices

general > card-capabilities-required

Guidance

This rule validates that agent cards declare all required capability properties in the capabilities section. Agent cards must specify whether they support streaming, push notifications, and state transition history tracking. These capability declarations enable agent integration and orchestration by informing consuming systems and brokers how to interact with the agent. Missing capability properties cause ambiguity and lead to integration failures, incorrect assumptions about agent behavior, or missed opportunities for advanced features. This rule applies to all agent cards in both broker definitions and external agent declarations across Agent Network specifications. It ensures complete capability transparency for all network participants.

Message

Agent Card must define all required capability properties in the capabilities section. Add streaming, pushNotifications, and stateTransitionHistory properties to clearly communicate agent functionality and integration requirements.

Examples

valid

schemaVersion: 1.0.0
brokers:
  my-broker:
    card:
      protocolVersion: "0.3.0"
      name: "My Broker"
      description: "A sample broker with all required capabilities"
      url: "https://my-broker.example.com"
      version: "1.0.0"
      provider:
        organization: "Example Corp"
        url: "https://example.com"
      # All three required capability properties are present
      capabilities:
        streaming: false
        pushNotifications: false
        stateTransitionHistory: false
        extensions: []
      defaultInputModes:
        - "application/json"
      defaultOutputModes:
        - "application/json"
      skills:
        - id: "coordination"
          name: "Agent Coordination"
          description: "Coordinates agent activities"
          tags: ["coordination"]
    spec:
      llm:
        ref:
          name: "openai-llm"
        configuration:
          model: "gpt-4"
      instructions:
        - "You are a helpful assistant"
      links:
        - agent:
            ref:
              name: "external-agent"

invalid

schemaVersion: 1.0.0
brokers:
  my-broker:
    card:
      protocolVersion: "0.3.0"
      name: "My Broker"
      description: "A sample broker missing capability property"
      url: "https://my-broker.example.com"
      version: "1.0.0"
      provider:
        organization: "Example Corp"
        url: "https://example.com"
      # Missing stateTransitionHistory - this should trigger the validation rule
      capabilities:
        streaming: false
        pushNotifications: false
        extensions: []
      defaultInputModes:
        - "application/json"
      defaultOutputModes:
        - "application/json"
      skills:
        - id: "coordination"
          name: "Agent Coordination"
          description: "Coordinates agent activities"
          tags: ["coordination"]
    spec:
      llm:
        ref:
          name: "openai-llm"
        configuration:
          model: "gpt-4"
      instructions:
        - "You are a helpful assistant"
      links:
        - agent:
            ref:
              name: "external-agent"

Applies to card

Constraint

Type: Declarative Validation