Managing Teams

Teams are multi-agent collaboration systems where multiple AI agents work together on complex workflows. This guide covers team creation, configuration, and management.

---

What Are Teams?

Teams enable multiple AI agents to collaborate on tasks that require specialized knowledge or multi-step workflows.

Key Concepts:

• Team Agents: Agents that belong to a team (with specific roles)
• Agent Roles: Manager, Orchestrator, or Member
• Connections: AI Delegation (bidirectional) or Handoff (one-way)
• Visual Designer: Flow-based canvas for designing team structures

Use Cases:

• Customer support escalation (Tier 1 → Tier 2 → Specialist)
• Sales workflows (Lead qualifier → Demo scheduler → Sales closer)
• Content creation (Researcher → Writer → Editor → Publisher)
• Multi-domain support (Product questions → Billing → Technical support)

---

Team List Page

Path: /teams

View Modes

Mode	Description	Use Case
Grid View	Card-based layout	Browsing and comparing teams visually
Table View	Compact row-based layout	Quickly scanning many teams

Toggle: View mode buttons in top-right corner

Search and Filtering

Search: Real-time search by team name or identifier

Team List Columns

Verified against app/types/domains/team.ts:

Column	Description	Source Field
Name	Team display name	name
Identifier	Unique slug	identifier
Description	Brief team summary	description
Agent Count	Number of agents in team	agent_count
Status	Active, Inactive, or Draft	status
Created	Creation timestamp	created_at
Actions	Quick action buttons	—

---

Creating Teams

Two paths:

1. Quick Create Form

Path: /teams/createInterface: Simple form with basic fields

Fields:

• Name (required): Team display name
• Identifier (required): Unique slug (auto-generated from name)
• Description (required): Brief summary of team purpose
• Image (optional): Team avatar/logo

Action: Creates team with no agents → redirect to Visual Designer to add agents

2. Visual Designer

Path: /teams/designerInterface: Flow-based canvas with drag-and-drop

Workflow:

1. Create new team (enter name, identifier, description)
2. Add agents to canvas
3. Connect agents with relationship lines
4. Configure roles and connection types
5. Save team

See: Visual Designer Guide for full designer documentation

---

Team Structure

Team Fields

From app/types/domains/team.ts:

{
  id: number,
  name: string,              // Team display name
  identifier: string,        // Unique slug (e.g., "support-team")
  description: string,       // Brief summary
  image?: string,            // Optional team avatar URL
  agents: TeamAgent[],       // Array of team agents
  suggested_prompts?: SuggestedPromptsConfig  // Conversation starters
}

Example:

{
  "name": "Customer Support Team",
  "identifier": "support-team",
  "description": "Multi-tier support with escalation to specialists",
  "image": "https://...",
  "agents": [
    { "id": 1, "name": "Tier 1 Support", "role": "member" },
    { "id": 2, "name": "Tier 2 Support", "role": "member" },
    { "id": 3, "name": "Support Manager", "role": "manager" }
  ]
}

---

Agent Roles

Every agent in a team has a role that defines its responsibility.

Role Types

Verified against app/types/domains/team.ts (role is implied via AgentConfiguration):

Role	Icon	Description	Capabilities
Manager	Crown	Coordinates team, delegates tasks	Can assign work, review outputs, make decisions
Orchestrator	Network	Routes messages to appropriate agents	Can analyze requests, route to specialists
Member	User	Executes specialized tasks	Focused expertise, reports to manager

Configuration: Set via agent's configuration.manager and configuration.orchestrator flags

Example:

{
  "name": "Support Manager",
  "configuration": {
    "manager": true,
    "orchestrator": false
  }
}

Role Assignment Best Practices

Manager (1 per team):

• Highest-level decision maker
• Reviews all outputs before final response
• Handles escalations
• Coordinates between specialists

Orchestrator (optional, 0-1 per team):

• Routes incoming requests to appropriate member
• No decision-making authority
• Pure routing logic

Members (2-10 per team):

• Specialized expertise (billing, technical, product, etc.)
• Execute specific tasks
• Report results to manager

Team Structure Recommendation:

• Small teams (2-4 agents): 1 manager + 2-3 members
• Medium teams (5-7 agents): 1 manager + 1 orchestrator + 3-5 members
• Large teams (8+ agents): Consider splitting into multiple teams

---

Agent Connections

Connections define how agents communicate and collaborate.

Connection Types

From team flow designer (implied in app/types/domains/team.ts via edge types):

Connection Type	Direction	Description	Use Case
AI Delegation	Bidirectional	Manager delegates task to member, member returns result	Complex problem-solving, review workflows
Handoff	One-way	Transfer conversation to another agent	Escalation, specialization routing

AI Delegation Flow:

Manager → "Research this topic" → Member
Member → "Here's the research" → Manager
Manager → Uses research to formulate response

Handoff Flow:

Tier 1 Support → Cannot solve issue → Handoff to Tier 2
Tier 2 Support → Takes over conversation

Configuring Connections

In Visual Designer:

1. Click and drag from one agent node to another
2. Select connection type (AI Delegation or Handoff)
3. Optionally add label (e.g., "Escalate technical issues")

Connection Rules:

• Manager → Member: Use AI Delegation (manager needs results back)
• Member → Member: Use Handoff (transfer ownership)
• Orchestrator → Member: Use Handoff (route to specialist)
• Member → Manager: Use AI Delegation (report results)

---

Team Agents

TeamAgent Interface

From app/types/domains/team.ts:

{
  id?: number,
  name: string,
  description: string,
  knowledgeSources: any[],
  tools: any[],
  tasks?: any[],
  configuration?: AgentConfiguration,
  isExistingAgent?: boolean,
  '@id'?: string,
  originalIndex?: number
}

Key Fields:

• isExistingAgent: If true, references existing agent by ID (not a new agent)
• configuration: Role flags, capabilities
• knowledge, tools: Resources available to this agent

Adding Agents to Teams

Two methods:

1. Reference Existing Agent

{
  "id": 123,
  "isExistingAgent": true
}

Effect: Team uses existing agent (no duplication)

2. Create New Team-Specific Agent

{
  "name": "Team-Specific Support Agent",
  "description": "Specialized for this team",
  "isExistingAgent": false,
  "configuration": {
    "manager": false,
    "reasoning": true
  }
}

Effect: Creates new agent scoped to this team

Recommendation: Use existing agents when possible to maintain consistency across teams.

---

Editing Teams

Two paths:

1. Quick Edit Form

Path: /teams/{id}/editInterface: Form view (same as create) Editable:

• Name, identifier, description, image
• Agent list (add/remove references)

Cannot edit: Agent roles, connections (use Visual Designer)

2. Visual Designer

Path: /teams/designer?team={id} or /teams/{id}/designerInterface: Flow-based canvas Editable: Everything (structure, roles, connections, positions)

Recommended for: Complex team restructuring

---

Team Actions

Per-Team Actions

Action	Icon	Description
Chat	Message bubble	Start conversation with team
Edit	Pencil	Open quick edit form
Designer	Network	Open visual designer
Delete	Trash	Permanently delete team

Row Click: Clicking anywhere on team row opens team detail view

Deleting Teams

Warning: Deletion is permanent

What gets deleted:

• Team configuration
• Agent connections and roles
• Team-specific agents (if created for team)

What is preserved:

• Referenced existing agents (not deleted)
• Historical sessions (sessions remain accessible)

Cannot delete if:

• Team has active sessions in progress
• Team is referenced by automation workflows

---

Team Metrics

From app/types/domains/team.ts:

{
  total_teams: number,
  active_teams: number,
  inactive_teams: number,
  total_team_agents: number,
  average_agents_per_team: number,
  teams_with_images: number
}

Display: Shown on teams dashboard at /teams (top metrics panel)

---

Suggested Prompts

Teams can have conversation starters like individual agents.

Field: suggested_promptsType: SuggestedPromptsConfig (same as agents)

Example:

{
  "suggested_prompts": [
    { "text": "I have a billing question", "icon": "credit-card" },
    { "text": "Technical support needed", "icon": "wrench" },
    { "text": "Talk to sales", "icon": "phone" }
  ]
}

Use Case: Guide users to the right team member

---

Team Workflows

Delegation Workflow

Scenario: User asks complex question requiring research

Flow:

1. Manager receives user message
2. Manager delegates research task to Researcher agent
3. Researcher performs research, returns results
4. Manager uses research to formulate response
5. Manager replies to user

Implementation: AI Delegation connections

Escalation Workflow

Scenario: Tier 1 support can't solve issue

Flow:

1. Tier 1 Support attempts to help
2. Tier 1 determines escalation needed
3. Handoff to Tier 2 Support
4. Tier 2 takes over conversation
5. User continues conversation with Tier 2

Implementation: Handoff connections

Routing Workflow

Scenario: User request needs specific specialist

Flow:

1. Orchestrator receives user message
2. Orchestrator analyzes intent (billing? technical? sales?)
3. Handoff to appropriate specialist
4. Specialist handles conversation

Implementation: Orchestrator with Handoff connections to specialists

---

Best Practices

Team Size

Optimal: 3-5 agents Maximum recommended: 7 agents Why: More agents = slower response times, higher costs, complexity

If you need 8+ agents: Split into multiple specialized teams

Role Distribution

Recommended ratios:

• 1 Manager : 3-5 Members
• 1 Orchestrator : 4-6 Members

Don't:

• Multiple managers (creates confusion)
• All members, no manager (no coordination)
• Too many orchestrators (adds latency)

Naming Conventions

Teams: Describe purpose, not structure

• ✅ "Customer Support Team"
• ❌ "Team with 5 agents"

Agents: Describe specialty or role

• ✅ "Billing Specialist"
• ✅ "Technical Support - Level 2"
• ❌ "Agent 1"

Connection Patterns

Star Pattern (Manager-centric):

      Member A
          ↑
     Manager ← User
          ↓
      Member B

Use for: Research teams, review workflows

Linear Pattern (Escalation):

User → Tier 1 → Tier 2 → Specialist

Use for: Support escalation, approval chains

Hub Pattern (Orchestrator-centric):

         Orchestrator ← User
         /    |    \
    Sales  Support  Product

Use for: Routing, department-based teams

---

Troubleshooting

Team Not Responding

Symptoms: Team conversation doesn't start or agents don't respond

Possible Causes:

1. No manager configured → No agent to coordinate
2. All agents disabled → Check agent status
3. Connection errors → Verify connections in Visual Designer

Fix: Open Visual Designer, verify structure and roles

Wrong Agent Responding

Symptoms: Orchestrator routes to wrong specialist

Cause: Orchestrator instructions unclear

Fix: Edit orchestrator agent instructions to clarify routing logic

Slow Response Times

Symptoms: Team takes 5+ seconds to respond

Causes:

• Too many agents (7+)
• Complex delegation chains (Manager → A → B → C)
• Heavy knowledge sources on multiple agents

Fix: Simplify team structure, reduce agents, optimize knowledge

---

Next Steps

• Visual Designer: Build teams with flow-based canvas
• Managing Agents: Create agents for teams
• Knowledge Sources: Add knowledge to team agents
• Chat Widget: Embed team on your website