Team Selector Strategy

This sample shows how to create teams that use AI-driven participant selection instead of fixed execution order:

• AI model analyzes conversation history to choose the next team member
• Template-based selector prompts with customizable decision logic
• Dynamic team coordination based on member descriptions and context
• Flexible team composition with agents and sub-teams

Setup

Run the quickstart command to get your cluster up and running:

make quickstart

You can create teams with selector strategy by applying the sample configuration:

kubectl apply -f samples/teams/selector-strategy.yaml

Basic Usage

Create a simple research team with selector strategy:

apiVersion: ark.mckinsey.com/v1alpha1
kind: Team
metadata:
  name: research-team
spec:
  strategy: selector
  members:
    - name: researcher
      type: agent
    - name: analyst
      type: agent
    - name: reviewer
      type: agent
  selector:
    model: default

Query the team and let AI choose the best participant for each step:

fark team research-team 'analyze market trends for electric vehicles'

The selector model will automatically choose which team member should respond based on the conversation context and member descriptions.

How It Works

1. Model Selection: LLM analyzes conversation history and selects next participant
2. Template Processing: Fills selector prompt with team roles, participants, and history
3. Participant Selection: Model returns name of selected team member
4. Execution: Selected member processes messages and adds response
5. Loop: Process repeats until max turns reached or team terminates

Template Variables

The selector prompt supports these template variables:

• {{.Roles}}: List of team members with descriptions
• {{.Participants}}: Comma-separated list of member names
• {{.History}}: Full conversation history

Custom Selector Prompts

You can customize the selection logic by providing your own selector prompt:

spec:
  selector:
    model: default
    selectorPrompt: |
      Select the best team member to respond next.
      
      Available roles: {{.Roles}}
      Conversation: {{.History}}
      Choose from: {{.Participants}}
      
      Return only the participant name.

Configuration Examples

Research Team

spec:
  strategy: selector
  members:
    - name: researcher
      type: agent
    - name: analyst  
      type: agent
    - name: reviewer
      type: agent
  selector:
    model: default
    selectorPrompt: |
      Research workflow coordinator. Select next participant:
      
      Roles: {{.Roles}}
      History: {{.History}}
      Options: {{.Participants}}
      
      Start with researcher, follow with analyst, end with reviewer.

Consulting Team

spec:
  strategy: selector
  members:
    - name: project-manager
      type: agent
    - name: consultant
      type: agent
  selector:
    model: gpt-4
    selectorPrompt: |
      Choose the most appropriate consultant based on expertise needed.
      
      Available: {{.Roles}}
      Context: {{.History}}
      Select from: {{.Participants}}

Agent Descriptions

Team member descriptions guide the selector model’s decision-making:

apiVersion: ark.mckinsey.com/v1alpha1
kind: Agent
metadata:
  name: research-analyst
spec:
  description: "Research and data analysis specialist"

Best Practices

• Keep descriptions concise (2-4 words)
• Focus on expertise area or role function
• Use consistent terminology across team
• Avoid overlapping descriptions

Selection Logic

Exact Match

Model response must exactly match team member name.

Fallback Behavior

If no exact match found:

• Uses first team member as fallback
• Logs selection method for debugging

Duplicate Prevention

Prevents same member responding consecutively by using first member as fallback.

Default Selector Prompt

When no custom selectorPrompt is specified:

You are in a role play game. The following roles are available:
{{.Roles}}.
Read the following conversation. Then select the next role from {{.Participants}} to play. Only return the role.

{{.History}}

Read the above conversation. Then select the next role from {{.Participants}} to play. Only return the role.

Monitoring

Check team execution and selection decisions:

kubectl get events -o json | jq -r '.items[] | select(.message | contains("research-team")) | "\(.lastTimestamp) \(.type) \(.reason) \(.message)"' | sort

Selection events are recorded with:

• Selected participant name
• Available participants list
• Selection method (exact_match, fallback_no_match)
• Team name and turn number

Cleanup

Delete the selector strategy team resources:

kubectl delete -f samples/teams/selector-strategy.yaml