Agent Network Best Practices

general > card-name-required

Guidance

This rule validates that every agent card includes a meaningful, nonempty name property. Agent names are the primary identifiers for agents within the network, making them recognizable to users, administrators, and other systems. A clear, descriptive name enables agent discovery, management, and communication within orchestration workflows.Without a name, agents can't be referenced, tracked, or debugged in operational scenarios. The rule applies to all agent cards, broker definitions, and external agent declarations, providing every agent with a clear identity that simplifies network understanding and operational management.

Message

Agent Card must include a meaningful name property. Add a clear, descriptive name that identifies the agent's purpose and makes it easily recognizable for users and administrators.

Examples

valid

schemaVersion: 1.0.0
brokers:
  my-broker:
    card:
      protocolVersion: "0.3.0"
      name: "Weather Coordination Broker"
      description: "A sample broker that coordinates weather-related agent activities"
      url: "https://my-broker.example.com"
      version: "1.0.0"
      provider:
        organization: "Example Corp"
        url: "https://example.com"
      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"
      # Missing name property - this should trigger the validation rule
      description: "A sample broker without a name"
      url: "https://my-broker.example.com"
      version: "1.0.0"
      provider:
        organization: "Example Corp"
        url: "https://example.com"
      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"

Applies to card

Constraint

Type: Declarative Validation