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:

devspace dev

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:
    agent: coordinator

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 agent will automatically choose which team member should respond based on the conversation context and member descriptions.

How It Works

1. Agent Selection: LLM analyzes conversation history and selects next participant
2. Template Processing: Fills selector prompt with team roles, participants, and history
3. Participant Selection: Agent 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:
    agent: coordinator
    selectorPrompt: |
      Select the best team member to respond next.
 
      Available roles: {{.Roles}}
      Conversation: {{.History}}
      Choose from: {{.Participants}}
 
      Return only the participant name.

Graph-Constrained Selector

You can combine the selector strategy with graph constraints to create workflows that have both structure and flexibility:

apiVersion: ark.mckinsey.com/v1alpha1
kind: Team
metadata:
  name: constrained-research-team
spec:
  strategy: selector
  selector:
    agent: coordinator
  members:
    - name: researcher
      type: agent
    - name: analyzer
      type: agent
    - name: writer
      type: agent
  graph:
    edges:
      - from: researcher
        to: analyzer
      - from: analyzer
        to: writer

How it works:

• The selector agent chooses the next participant, but only from members allowed by the graph edges
• If only one legal transition exists, the system uses it directly (optimization)
• If multiple legal transitions exist, the selector agent chooses from those candidates
• This combines the flexibility of AI selection with the structure of graph workflows

See Team Strategies for more details.

Configuration Examples

Research Team

spec:
  strategy: selector
  members:
    - name: researcher
      type: agent
    - name: analyst
      type: agent
    - name: reviewer
      type: agent
  selector:
    agent: coordinator
    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:
    agent: coordinator
    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 agent’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