Platform Hierarchy

Understanding how Deeployd organizes workspaces, apps, teams, and agents is essential for building effective AI workforces.

The Big Picture

Deeployd mirrors how real organizations work:

Your Company (Tenant)
├── IT Department (App)
│   ├── Helpdesk Team
│   │   ├── Triage Agent
│   │   ├── Password Reset Agent
│   │   └── FAQ Agent
│   └── Infrastructure Team
│       ├── Monitoring Agent
│       └── Incident Response Agent
│
├── HR Department (App)
│   └── Employee Services Team
│       ├── Onboarding Agent
│       └── Benefits Agent
│
└── Sales Department (App)
    └── Lead Generation Team
        ├── Qualifier Agent
        └── Scheduler Agent

Hierarchy Levels

Tenant (Organization)

The top level. One tenant = one organization.

What it contains:

• All users, agents, and resources
• Billing and subscription
• Global settings and security policies

Real-world analogy: Your company

// Tenant information
const tenant = await deeployd.tenants.get();
// { id: 'tenant-123', name: 'Acme Corp', plan: 'business' }

App (Department/Product)

Logical groupings within your tenant.

Use cases:

• Separate departments (IT, HR, Sales)
• Different products or services
• Client projects (for agencies)
• Development vs production

Real-world analogy: A department or business unit

// Create an app
const app = await deeployd.apps.create({
  name: 'IT Department',
  description: 'Internal IT support and infrastructure'
});

Team

Groups of agents that work together.

Use cases:

• Related agents that collaborate
• Shared context and memory
• Common escalation paths

Real-world analogy: A team within a department

// Create a team within an app
const team = await deeployd.teams.create({
  appId: app.id,
  name: 'Helpdesk',
  description: 'First-line IT support'
});

Agent

Individual AI workers that perform tasks.

What agents have:

• System prompt (personality, rules, knowledge)
• Tools (capabilities)
• Memory (context)
• Parent/child relationships (escalation)

Real-world analogy: An employee with a specific role

// Create an agent in a team
const agent = await deeployd.agents.create({
  teamId: team.id,
  name: 'Triage Agent',
  systemPrompt: 'You route IT requests to the right specialist...'
});

How They Work Together

Inheritance

Settings flow down the hierarchy:

Tenant (Security policies, API limits)
  └── App (Integrations, shared tools)
      └── Team (Shared memory, escalation rules)
          └── Agent (Specific prompt, specialized tools)

Level	Inherits From	Example Settings
Agent	Team, App, Tenant	Tools, memory, permissions
Team	App, Tenant	Integrations, policies
App	Tenant	Security, billing
Tenant	Platform	Global limits

Context Sharing

Agents in the same team can share context:

// Team-level memory is accessible to all agents
await deeployd.memory.set({
  teamId: team.id,
  key: 'current_incident',
  value: { id: 'INC001', status: 'investigating' }
});

// Any agent in the team can read it
const incident = await deeployd.memory.get({
  agentId: triageAgent.id,
  key: 'current_incident'
});

Escalation Paths

Agents can delegate to or escalate to other agents:

// Set up escalation
await deeployd.agents.update({
  agentId: triageAgent.id,
  escalateTo: seniorAgent.id,
  escalationRules: {
    conditions: ['user requests human', 'complexity > 7'],
    action: 'transfer'
  }
});

Practical Examples

Example 1: IT Support Structure

Acme Corp (Tenant)
└── IT Support (App)
    ├── Helpdesk (Team)
    │   ├── Triage Agent
    │   │   └── Routes requests, answers FAQs
    │   ├── Password Agent
    │   │   └── Handles password resets
    │   └── Software Agent
    │       └── Processes software requests
    │
    └── Infrastructure (Team)
        ├── Monitor Agent
        │   └── Watches dashboards, alerts
        └── Incident Agent
            └── Coordinates incident response

Why this structure?

• Helpdesk and Infrastructure have different responsibilities
• Agents in each team share relevant context
• Triage can escalate to Infrastructure when needed

Example 2: Agency Structure

Digital Agency (Tenant)
├── Client: Acme Corp (App)
│   └── Support Team
│       └── Support Agent (customized for Acme)
│
├── Client: TechStart (App)
│   └── Support Team
│       └── Support Agent (customized for TechStart)
│
└── Internal (App)
    └── Operations Team
        └── Billing Agent

Why this structure?

• Each client is isolated in their own app
• Agents are customized per client
• Internal operations are separate

Example 3: Product Company

SaaS Company (Tenant)
├── Core Product (App)
│   ├── Customer Success
│   │   ├── Onboarding Agent
│   │   └── Health Check Agent
│   └── Technical Support
│       ├── Tier 1 Agent
│       └── Tier 2 Agent
│
└── Enterprise Product (App)
    └── Dedicated Support
        └── Enterprise Agent (with extra capabilities)

Why this structure?

• Different products have different needs
• Enterprise customers get dedicated support
• Tier 1 and Tier 2 support are clearly separated

Best Practices

Naming Conventions

Use clear, consistent names:

✅ Good
- App: "IT Department"
- Team: "Helpdesk"
- Agent: "Password Reset Agent"

❌ Bad
- App: "Dept1"
- Team: "Team A"
- Agent: "Agent 1"

When to Create New Apps

Create a new app when:

• Different department or business unit
• Different client (agencies)
• Different product line
• Need isolated data and integrations

When to Create New Teams

Create a new team when:

• Agents need to share context
• Agents work on related tasks
• Common escalation paths needed
• Different specializations within an app

When to Create New Agents

Create a new agent when:

• Distinct role or responsibility
• Different system prompt needed
• Different tools required
• Specialized knowledge domain

API Reference

List Hierarchy

// Get full hierarchy
const hierarchy = await deeployd.tenants.getHierarchy();

/*
{
  tenant: { id: 'tenant-123', name: 'Acme Corp' },
  apps: [
    {
      id: 'app-456',
      name: 'IT Department',
      teams: [
        {
          id: 'team-789',
          name: 'Helpdesk',
          agents: [
            { id: 'agent-abc', name: 'Triage Agent' },
            { id: 'agent-def', name: 'Password Agent' }
          ]
        }
      ]
    }
  ]
}
*/

Move Resources

// Move agent to different team
await deeployd.agents.move({
  agentId: 'agent-123',
  toTeamId: 'team-456'
});

// Move team to different app
await deeployd.teams.move({
  teamId: 'team-123',
  toAppId: 'app-456'
});

---

Next: Learn about the Agent Lifecycle to understand how agents process requests.