Teams

Teams enable multiple agents to work together on complex tasks, sharing context and coordinating through hierarchical or collaborative structures.

Why Teams?

Single agents have limitations:

• Specialization: One agent can't be expert in everything
• Scale: Complex tasks require parallel execution
• Oversight: Critical decisions need multiple perspectives
• Coordination: Long-running processes need orchestration

Teams solve these by:

• Combining specialist agents with complementary skills
• Enabling parallel task execution
• Providing hierarchical delegation
• Sharing context and artifacts

Team Concepts

Team Structure

┌──────────────────────────────────────────────┐
│                    Team                       │
├──────────────────────────────────────────────┤
│  ┌─────────────┐                             │
│  │    Lead     │ ←── Coordinator/Manager     │
│  └──────┬──────┘                             │
│         │                                    │
│    ┌────┼────┐                               │
│    ▼    ▼    ▼                               │
│  ┌───┐┌───┐┌───┐                             │
│  │ A ││ B ││ C │ ←── Specialist Agents       │
│  └───┘└───┘└───┘                             │
│                                              │
│  ┌──────────────────────────────────────┐    │
│  │         Shared Storage               │    │
│  │  (Context, Artifacts, Decisions)     │    │
│  └──────────────────────────────────────┘    │
└──────────────────────────────────────────────┘

Team Templates

Templates define reusable team configurations:

interface TeamTemplate {
  name: string
  category: string
  description: string
  agents: TeamTemplateAgent[]
  sharedOnboarding?: JSONSchema
  orchestration?: OrchestrationConfig
  interactionRules?: InteractionRule[]
}

Creating Teams

From Template

// List available templates
const templates = await client.teams.listTemplates()

// Create team from template
const team = await client.teams.createFromTemplate({
  templateId: 'enterprise-deployment',
  name: 'Acme Deployment Team',
  workspaceId: 'ws-123',
  onboardingAnswers: {
    customerName: 'Acme Corporation',
    customerDomain: 'acme.com',
    deploymentType: 'sso'
  }
})

Manual Creation

const team = await client.teams.create({
  name: 'Sales Support Team',
  workspaceId: 'ws-123',
  agents: [
    {
      id: 'coordinator',
      name: 'Sales Coordinator',
      role: 'Team Lead',
      systemPrompt: 'You coordinate the sales support team...',
      tools: [{ name: 'delegate_task' }, { name: 'escalate' }],
      hierarchy: {
        level: 1,
        canDelegate: true,
        subordinates: ['qualifier', 'researcher', 'closer']
      }
    },
    {
      id: 'qualifier',
      name: 'Lead Qualifier',
      role: 'Lead Qualification',
      systemPrompt: 'You qualify incoming leads...',
      hierarchy: { level: 2, reportsTo: 'coordinator' }
    },
    {
      id: 'researcher',
      name: 'Company Researcher',
      role: 'Research Specialist',
      systemPrompt: 'You research companies and contacts...',
      hierarchy: { level: 2, reportsTo: 'coordinator' }
    },
    {
      id: 'closer',
      name: 'Deal Closer',
      role: 'Sales Specialist',
      systemPrompt: 'You help close deals...',
      hierarchy: { level: 2, reportsTo: 'coordinator' }
    }
  ]
})

Team Templates

Built-in Templates

Deeployd provides pre-built templates:

Template	Description
enterprise-deployment	SSO/SCIM deployment team
sales-team	Sales qualification and closing
support-team	Customer support escalation
content-team	Content creation and review
research-team	Research and analysis

Template Structure

const enterpriseDeploymentTemplate: TeamTemplate = {
  name: 'Enterprise Deployment Team',
  category: 'operations',
  description: 'Complete team for enterprise SSO/SCIM deployments',
  tags: ['enterprise', 'deployment', 'sso', 'scim'],

  agents: [
    {
      id: 'deployment_lead',
      name: 'Enterprise Deployment Lead',
      role: 'Deployment Project Manager',
      description: 'Coordinates deployment activities',
      templateId: 'deployment-lead-v1',
      tools: [
        { name: 'project_status' },
        { name: 'escalate_to_human' },
        { name: 'delegate_to_agent' },
        { name: 'request_approval' }
      ],
      hierarchy: {
        level: 1,
        canDelegate: true,
        subordinates: ['sso_agent', 'scim_agent', 'security_agent']
      }
    },
    {
      id: 'sso_agent',
      name: 'SSO Specialist',
      role: 'SSO Configuration Expert',
      description: 'Handles SAML/OIDC configuration',
      templateId: 'sso-specialist-v1',
      tools: [
        { name: 'configure_saml' },
        { name: 'configure_oidc' },
        { name: 'test_sso_flow' }
      ],
      hierarchy: {
        level: 2,
        reportsTo: 'deployment_lead'
      }
    },
    {
      id: 'scim_agent',
      name: 'SCIM Specialist',
      role: 'SCIM Provisioning Expert',
      description: 'Handles user provisioning',
      templateId: 'scim-specialist-v1',
      tools: [
        { name: 'configure_scim' },
        { name: 'map_attributes' },
        { name: 'test_provisioning' }
      ],
      hierarchy: {
        level: 2,
        reportsTo: 'deployment_lead'
      }
    },
    {
      id: 'security_agent',
      name: 'Security Reviewer',
      role: 'Security Assessment',
      description: 'Reviews security configuration',
      templateId: 'security-reviewer-v1',
      tools: [
        { name: 'security_scan' },
        { name: 'compliance_check' }
      ],
      hierarchy: {
        level: 2,
        reportsTo: 'deployment_lead'
      }
    }
  ],

  sharedOnboarding: {
    type: 'object',
    properties: {
      customerName: { type: 'string', title: 'Customer Name' },
      customerDomain: { type: 'string', title: 'Customer Domain' },
      idpType: {
        type: 'string',
        title: 'Identity Provider',
        enum: ['okta', 'azure_ad', 'google', 'onelogin', 'other']
      },
      targetGoLive: { type: 'string', format: 'date', title: 'Target Go-Live' }
    },
    required: ['customerName', 'customerDomain', 'idpType']
  },

  orchestration: {
    mode: 'hierarchical',
    entryAgentId: 'deployment_lead',
    escalationPath: ['deployment_lead', 'support']
  },

  interactionRules: [
    {
      id: 'security_escalation',
      trigger: 'security_concern',
      action: 'escalate',
      target: 'security_agent',
      priority: 'high'
    },
    {
      id: 'approval_required',
      trigger: 'phase_complete',
      action: 'request_approval',
      target: 'external_participant'
    }
  ]
}

Shared Onboarding

Teams share context through shared onboarding:

Define Schema

sharedOnboarding: {
  type: 'object',
  properties: {
    // Customer context
    customerName: { type: 'string' },
    industry: { type: 'string' },
    size: { type: 'string', enum: ['startup', 'smb', 'enterprise'] },

    // Technical context
    currentStack: { type: 'array', items: { type: 'string' } },
    constraints: { type: 'string' },

    // Project context
    goals: { type: 'array', items: { type: 'string' } },
    timeline: { type: 'string' }
  },
  required: ['customerName', 'goals']
}

Provide Answers

const team = await client.teams.createFromTemplate({
  templateId: 'enterprise-deployment',
  onboardingAnswers: {
    customerName: 'Acme Corporation',
    industry: 'Technology',
    size: 'enterprise',
    currentStack: ['Okta', 'Slack', 'Jira'],
    goals: ['SSO deployment', 'User provisioning', 'Security compliance'],
    timeline: 'Q1 2024'
  }
})

Access in Agents

All team agents receive shared context:

// Each agent's system prompt includes:
const contextPrompt = `
## Customer Context
- Customer: ${onboardingAnswers.customerName}
- Industry: ${onboardingAnswers.industry}
- Size: ${onboardingAnswers.size}

## Technical Context
- Current Stack: ${onboardingAnswers.currentStack.join(', ')}
- Constraints: ${onboardingAnswers.constraints}

## Project Goals
${onboardingAnswers.goals.map(g => `- ${g}`).join('\n')}

Timeline: ${onboardingAnswers.timeline}
`

Orchestration Modes

Hierarchical

Lead agent coordinates specialists:

orchestration: {
  mode: 'hierarchical',
  entryAgentId: 'lead',
  escalationPath: ['lead', 'supervisor', 'human']
}

User Message
     │
     ▼
┌─────────┐
│  Lead   │ ←── Entry point
└────┬────┘
     │ Delegates
     ├───────────────┬───────────────┐
     ▼               ▼               ▼
┌─────────┐    ┌─────────┐    ┌─────────┐
│Specialist│    │Specialist│    │Specialist│
│    A     │    │    B     │    │    C     │
└─────────┘    └─────────┘    └─────────┘

Collaborative

Agents work as peers:

orchestration: {
  mode: 'collaborative',
  router: 'intent-based',
  routingRules: [
    { intent: 'technical_question', target: 'tech_agent' },
    { intent: 'billing_question', target: 'billing_agent' },
    { intent: 'general', target: 'general_agent' }
  ]
}

Swarm

Agents spawn dynamically:

orchestration: {
  mode: 'swarm',
  spawnerAgentId: 'coordinator',
  maxConcurrentAgents: 10,
  agentPool: ['worker_a', 'worker_b', 'worker_c']
}

Interaction Rules

Rules define automatic behaviors:

Escalation Rules

interactionRules: [
  {
    id: 'complexity_escalation',
    trigger: {
      type: 'complexity_score',
      threshold: 0.8
    },
    action: 'escalate',
    target: 'senior_agent',
    priority: 'high'
  },
  {
    id: 'sentiment_escalation',
    trigger: {
      type: 'sentiment_score',
      threshold: -0.5
    },
    action: 'escalate',
    target: 'retention_agent',
    priority: 'urgent'
  }
]

Handoff Rules

interactionRules: [
  {
    id: 'billing_handoff',
    trigger: {
      type: 'intent',
      value: 'billing_dispute'
    },
    action: 'handoff',
    target: 'billing_specialist',
    context: ['conversation_history', 'customer_info']
  }
]

Approval Rules

interactionRules: [
  {
    id: 'high_value_approval',
    trigger: {
      type: 'action',
      value: 'refund',
      condition: 'amount > 1000'
    },
    action: 'request_approval',
    target: 'manager',
    timeout: '4h'
  }
]

Shared Storage

Teams have shared storage for artifacts and decisions:

Store Artifacts

// Store a document
await client.teams.storeArtifact('team-123', {
  key: 'requirements_doc',
  type: 'document',
  content: { /* document content */ },
  metadata: {
    createdBy: 'sso_agent',
    version: '1.0'
  }
})

Retrieve Artifacts

// Get specific artifact
const doc = await client.teams.getArtifact('team-123', 'requirements_doc')

// List all artifacts
const artifacts = await client.teams.listArtifacts('team-123', {
  type: 'document',
  createdBy: 'sso_agent'
})

Share Decisions

// Record a decision
await client.teams.recordDecision('team-123', {
  key: 'idp_selection',
  decision: 'okta',
  rationale: 'Customer already uses Okta for other apps',
  madeBy: 'sso_agent',
  approvedBy: 'customer_it_admin'
})

// Query decisions
const decisions = await client.teams.listDecisions('team-123')

Team API

List Team Members

const members = await client.teams.listMembers('team-123')

for (const member of members) {
  console.log({
    id: member.id,
    name: member.name,
    role: member.role,
    status: member.status,
    currentTask: member.currentTask
  })
}

Send Message to Team

// Message goes to entry agent
const response = await client.teams.message('team-123', {
  content: 'Please configure SSO for our Okta instance',
  attachments: [{ type: 'file', url: '...' }]
})

Direct Message to Agent

// Message specific agent
const response = await client.teams.messageAgent('team-123', 'sso_agent', {
  content: 'What SAML attributes do we need?'
})

Get Team Status

const status = await client.teams.getStatus('team-123')

console.log({
  activeAgents: status.activeAgents,
  currentTasks: status.currentTasks,
  pendingApprovals: status.pendingApprovals,
  lastActivity: status.lastActivity
})

Best Practices

1. Clear Role Definitions

Each agent should have a focused role:

// ✅ Good - focused roles
agents: [
  { id: 'qualifier', role: 'Lead Qualification' },
  { id: 'researcher', role: 'Company Research' },
  { id: 'closer', role: 'Deal Closing' }
]

// ❌ Bad - overlapping roles
agents: [
  { id: 'sales1', role: 'Sales Agent' },
  { id: 'sales2', role: 'Sales Agent' }
]

2. Appropriate Hierarchy

Match hierarchy to task complexity:

// Simple task - flat structure
orchestration: { mode: 'collaborative' }

// Complex coordination - hierarchical
orchestration: {
  mode: 'hierarchical',
  entryAgentId: 'coordinator'
}

3. Shared Context

Ensure all agents have necessary context:

sharedOnboarding: {
  properties: {
    // Include everything agents need
    customerName: { type: 'string' },
    goals: { type: 'array' },
    constraints: { type: 'string' },
    timeline: { type: 'string' }
  }
}

4. Clear Escalation Paths

Define when and how to escalate:

interactionRules: [
  {
    id: 'stuck_escalation',
    trigger: { type: 'no_progress', duration: '5m' },
    action: 'escalate',
    target: 'lead'
  }
]

---

Next: Learn about Process Orchestration for enterprise deployment workflows.