Agent Network Best Practices

general > limit-broker-links

Guidance

This rule validates that brokers don't have more than 10 agent links in their specification. Brokers are orchestration agents that coordinate activities across multiple agents. Excessive agent links create complex orchestration patterns that are difficult to manage, debug, and optimize. Limiting broker links enforces clear orchestration design where each broker has a focused set of agent relationships instead of coordinating an unmanageable number of participants. This constraint maintains broker performance by preventing excessive coordination overhead and requires the decomposition of complex orchestration scenarios into multiple specialized brokers. The rule applies to broker specifications in Agent Network definitions. It provides an architectural guideline for scalable, maintainable orchestration patterns that balance flexibility with operational manageability.

Message

Broker has too many agent links defined. Limit the number of agent links to 10 or fewer to maintain optimal performance and reduce orchestration complexity.

Examples

valid

schemaVersion: 1.0.0
brokers:
  customer-service-broker:
    card:
      protocolVersion: "0.3.0"
      name: "Customer Service Broker"
      description: "Coordinates customer service operations with limited links"
      url: "https://customer-service-broker.example.com"
      version: "1.0.0"
      provider:
        organization: "Customer Solutions Inc"
        url: "https://customer-solutions.com"
      capabilities:
        streaming: false
        pushNotifications: false
        stateTransitionHistory: false
        extensions: []
      defaultInputModes:
        - "application/json"
      defaultOutputModes:
        - "application/json"
      skills:
        - id: "customer-service"
          name: "Customer Service"
          description: "Handles customer service operations"
          tags: ["customer-service", "support"]
    spec:
      llm:
        ref:
          name: my-openai
        configuration:
          model: "gpt-4"
      instructions:
        - "You are a customer service coordinator"
      links:
        - agent:
            ref:
              name: customer-support-agent
        - agent:
            ref:
              name: billing-agent
        - agent:
            ref:
              name: technical-support-agent
llms:
  my-openai:
    provider: openai
    description: "OpenAI GPT-4 model for reasoning"

invalid

schemaVersion: 1.0.0
brokers:
  customer-service-broker:
    card:
      protocolVersion: "0.3.0"
      name: "Customer Service Broker"
      description: "Coordinates customer service operations with too many links"
      url: "https://customer-service-broker.example.com"
      version: "1.0.0"
      provider:
        organization: "Customer Solutions Inc"
        url: "https://customer-solutions.com"
      capabilities:
        streaming: false
        pushNotifications: false
        stateTransitionHistory: false
        extensions: []
      defaultInputModes:
        - "application/json"
      defaultOutputModes:
        - "application/json"
      skills:
        - id: "customer-service"
          name: "Customer Service"
          description: "Handles customer service operations"
          tags: ["customer-service", "support"]
    spec:
      llm:
        ref:
          name: my-openai
        configuration:
          model: "gpt-4"
      instructions:
        - "You are a customer service coordinator"
      # 11 links - exceeds the maxCount: 10 limit
      links:
        - agent:
            ref:
              name: customer-support-agent
        - agent:
            ref:
              name: billing-agent
        - agent:
            ref:
              name: technical-support-agent
        - agent:
            ref:
              name: order-management-agent
        - agent:
            ref:
              name: inventory-agent
        - agent:
            ref:
              name: shipping-agent
        - agent:
            ref:
              name: returns-agent
        - agent:
            ref:
              name: loyalty-agent
        - agent:
            ref:
              name: analytics-agent
        - agent:
            ref:
              name: notification-agent
        - agent:
            ref:
              name: compliance-agent
llms:
  my-openai:
    provider: openai
    description: "OpenAI GPT-4 model for reasoning"

Applies to Broker

Constraint

Type: Declarative Validation