Agent Network Best Practices

general > card-url-required

Guidance

This rule validates that every agent card includes a valid, nonempty endpoint URL property. The URL specifies where the agent can be accessed for communication and integration. This URL is the fundamental connection point for agent interactions within the network. Without a valid endpoint URL, other agents, brokers, and systems can't establish communication with the agent, making it unusable within orchestration workflows. This rule applies to all agent cards in broker definitions and external agent declarations across Agent Network specifications. Every agent must provide the necessary connectivity information for network integration and communication.

Message

Agent Card must include a valid endpoint URL. Add a complete URL that specifies where the agent can be accessed to enable proper communication and integration with other services.

Examples

valid

schemaVersion: 1.0.0
brokers:
  my-broker:
    card:
      protocolVersion: "0.3.0"
      name: "Weather API Broker"
      description: "A sample broker with a valid endpoint URL"
      url: "https://weather-api-broker.example.com/v1"
      version: "1.0.0"
      provider:
        organization: "Weather Solutions Inc"
        url: "https://weather-solutions.com"
      capabilities:
        streaming: false
        pushNotifications: false
        stateTransitionHistory: false
        extensions: []
      defaultInputModes:
        - "application/json"
      defaultOutputModes:
        - "application/json"
      skills:
        - id: "weather-api"
          name: "Weather API Access"
          description: "Provides access to weather data"
          tags: ["weather", "api"]
    spec:
      llm:
        ref:
          name: "openai-llm"
        configuration:
          model: "gpt-4"
      instructions:
        - "You are a weather API assistant"
      links:
        - agent:
            ref:
              name: "external-agent"

invalid

schemaVersion: 1.0.0
brokers:
  my-broker:
    card:
      protocolVersion: "0.3.0"
      name: "Weather API Broker"
      description: "A sample broker missing endpoint URL"
      # Missing url property - this should trigger the validation rule
      version: "1.0.0"
      provider:
        organization: "Weather Solutions Inc"
        url: "https://weather-solutions.com"
      capabilities:
        streaming: false
        pushNotifications: false
        stateTransitionHistory: false
        extensions: []
      defaultInputModes:
        - "application/json"
      defaultOutputModes:
        - "application/json"
      skills:
        - id: "weather-api"
          name: "Weather API Access"
          description: "Provides access to weather data"
          tags: ["weather", "api"]
    spec:
      llm:
        ref:
          name: "openai-llm"
        configuration:
          model: "gpt-4"
      instructions:
        - "You are a weather API assistant"
      links:
        - agent:
            ref:
              name: "external-agent"

Applies to card

Constraint

Type: Declarative Validation