Execution Model

Learn how Deeployd executes tasks, schedules, triggers, and workflows.

Execution Types

Deeployd supports several execution patterns:

Type	Trigger	Use Case
Chat	User message	Interactive conversations
Task	Manual or API call	One-off jobs
Schedule	Cron expression	Recurring jobs
Trigger	Webhook event	Event-driven automation
Workflow	Any of the above	Multi-step processes

Tasks

Tasks are single executions of an agent with specific input.

Creating a Task

const task = await deeployd.tasks.create({
  agentId: 'agent-123',
  name: 'Generate Weekly Report',
  input: {
    message: 'Generate a summary of this week\'s support tickets',
    context: { startDate: '2024-01-08', endDate: '2024-01-14' }
  }
});

Task Lifecycle

┌─────────┐    ┌─────────┐    ┌─────────┐    ┌───────────┐
│ Pending │───▶│ Running │───▶│ Success │ or │  Failed   │
└─────────┘    └─────────┘    └─────────┘    └───────────┘
                   │                              │
                   │         ┌─────────┐         │
                   └────────▶│ Timeout │◀────────┘
                             └─────────┘

Task States

State	Description
`pending`	Created, waiting to execute
`running`	Currently executing
`success`	Completed successfully
`failed`	Execution failed
`timeout`	Exceeded time limit
`cancelled`	Manually cancelled

Running Tasks

// Run a task immediately
const result = await deeployd.tasks.run(task.id);

// Run and wait for completion
const result = await deeployd.tasks.runSync(task.id, {
  timeout: 60000 // 60 seconds
});

// Check task status
const status = await deeployd.tasks.get(task.id);
console.log(status.state); // 'success'
console.log(status.output); // Agent's response

Schedules

Schedules run agents automatically on a recurring basis.

Creating a Schedule

const schedule = await deeployd.schedules.create({
  name: 'Daily Health Check',
  agentId: 'monitoring-agent',
  cron: '0 9 * * *', // 9 AM daily
  timezone: 'America/New_York',
  input: {
    message: 'Run daily health checks on all systems'
  }
});

Cron Syntax

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday = 0)
│ │ │ │ │
* * * * *

Common patterns:

Pattern	Cron	Description
Every hour	`0 * * * *`	Top of every hour
Daily at 9am	`0 9 * * *`	9:00 AM every day
Weekdays at 8am	`0 8 * * 1-5`	8:00 AM Mon-Fri
Weekly on Monday	`0 9 * * 1`	9:00 AM Monday
Monthly on 1st	`0 9 1 * *`	9:00 AM 1st of month

Managing Schedules

// Pause a schedule
await deeployd.schedules.pause(schedule.id);

// Resume a schedule
await deeployd.schedules.resume(schedule.id);

// Run schedule immediately (ad-hoc)
await deeployd.schedules.runNow(schedule.id);

// View execution history
const history = await deeployd.schedules.getExecutions(schedule.id);

Triggers

Triggers execute agents in response to external events.

Webhook Triggers

Receive HTTP requests from external systems:

const trigger = await deeployd.triggers.create({
  name: 'New Support Ticket',
  type: 'webhook',
  agentId: 'triage-agent',
  config: {
    path: '/webhooks/tickets',
    method: 'POST',
    secret: 'whsec_...' // For signature verification
  }
});

// Returns a URL like:
// https://api.deeployd.com/webhooks/t/trigger-123/tickets

Processing Webhook Data

The agent receives the webhook payload in context:

// Agent receives:
{
  message: 'New webhook received',
  context: {
    trigger: 'webhook',
    payload: {
      ticketId: 'TICKET-001',
      subject: 'Login not working',
      priority: 'high',
      customer: 'acme@example.com'
    },
    headers: {
      'content-type': 'application/json',
      'x-webhook-signature': '...'
    }
  }
}

Event Triggers

Listen to platform events:

const trigger = await deeployd.triggers.create({
  name: 'On Conversation Complete',
  type: 'event',
  agentId: 'analytics-agent',
  config: {
    events: ['conversation.completed', 'conversation.escalated']
  }
});

Available events:

Event	Description
`conversation.started`	New conversation begins
`conversation.completed`	Conversation ends
`conversation.escalated`	Agent escalates to another
`task.completed`	Task finishes
`task.failed`	Task fails
`schedule.executed`	Schedule runs
`agent.error`	Agent encounters error

Workflows

Workflows orchestrate multiple agents and steps.

Workflow Structure

┌─────────────────────────────────────────────────────┐
│                     WORKFLOW                        │
├─────────────────────────────────────────────────────┤
│                                                     │
│   ┌─────────┐    ┌─────────┐    ┌─────────┐       │
│   │ Step 1  │───▶│ Step 2  │───▶│ Step 3  │       │
│   │ Triage  │    │Classify │    │ Route   │       │
│   └─────────┘    └─────────┘    └────┬────┘       │
│                                      │            │
│                       ┌──────────────┼────────────┤
│                       │              │            │
│                       ▼              ▼            │
│                 ┌─────────┐    ┌─────────┐       │
│                 │ Step 4a │    │ Step 4b │       │
│                 │Tech Sup │    │Billing  │       │
│                 └─────────┘    └─────────┘       │
│                                                   │
└─────────────────────────────────────────────────────┘

Creating a Workflow

const workflow = await deeployd.workflows.create({
  name: 'Support Ticket Processing',
  trigger: {
    type: 'webhook',
    path: '/tickets'
  },
  steps: [
    {
      id: 'triage',
      type: 'agent',
      agentId: 'triage-agent',
      input: {
        message: 'Analyze this support ticket: {{trigger.payload}}'
      }
    },
    {
      id: 'classify',
      type: 'agent',
      agentId: 'classifier-agent',
      dependsOn: ['triage'],
      input: {
        message: 'Classify: {{steps.triage.output}}'
      }
    },
    {
      id: 'route',
      type: 'condition',
      dependsOn: ['classify'],
      conditions: [
        {
          if: '{{steps.classify.output.category}} == "technical"',
          goto: 'tech-support'
        },
        {
          if: '{{steps.classify.output.category}} == "billing"',
          goto: 'billing-support'
        }
      ],
      default: 'general-support'
    },
    {
      id: 'tech-support',
      type: 'agent',
      agentId: 'tech-agent'
    },
    {
      id: 'billing-support',
      type: 'agent',
      agentId: 'billing-agent'
    },
    {
      id: 'general-support',
      type: 'agent',
      agentId: 'general-agent'
    }
  ]
});

Step Types

Type	Description
`agent`	Execute an agent
`condition`	Branch based on conditions
`parallel`	Run steps concurrently
`wait`	Pause for time or event
`http`	Make HTTP request
`transform`	Transform data
`human`	Wait for human approval

Workflow Variables

Access data from triggers and previous steps:

// Trigger data
'{{trigger.payload.ticketId}}'
'{{trigger.headers.x-custom-header}}'

// Previous step output
'{{steps.triage.output}}'
'{{steps.classify.output.category}}'

// Built-in variables
'{{workflow.id}}'
'{{workflow.startedAt}}'
'{{env.API_KEY}}'

Error Handling

Configure how workflows handle failures:

{
  id: 'risky-step',
  type: 'agent',
  agentId: 'agent-123',
  onError: {
    strategy: 'retry',
    maxRetries: 3,
    backoff: 'exponential',
    fallback: 'fallback-step' // Go here if all retries fail
  }
}

Error strategies:

Strategy	Description
`fail`	Stop workflow immediately
`retry`	Retry with backoff
`skip`	Skip step, continue workflow
`fallback`	Go to fallback step

Execution Limits

Default limits for executions:

Resource	Limit	Notes
Task timeout	5 minutes	Configurable up to 30 min
Workflow timeout	30 minutes	Configurable up to 24 hours
Steps per workflow	50	Contact support for more
Concurrent tasks	10	Per tenant, varies by plan
Schedules	100	Per tenant
Webhooks/sec	100	Per endpoint

Monitoring Executions

View Execution Status

// Get workflow execution
const execution = await deeployd.workflows.getExecution(executionId);

console.log(execution.state); // 'running'
console.log(execution.currentStep); // 'classify'
console.log(execution.steps); // Status of each step

Execution Dashboard

Monitor all executions in the Dashboard:

Dashboard → Executions
├── Active (currently running)
├── Recent (last 24 hours)
├── Failed (errors)
└── Scheduled (upcoming)

Webhooks for Execution Events

Get notified when executions complete:

await deeployd.webhooks.create({
  url: 'https://your-app.com/webhooks',
  events: [
    'workflow.completed',
    'workflow.failed',
    'task.completed',
    'task.failed'
  ]
});

Next: Learn about Memory & Context to understand how agents remember information.

Execution Types​

Tasks​

Creating a Task​

Task Lifecycle​

Task States​

Running Tasks​

Schedules​

Creating a Schedule​

Cron Syntax​

Managing Schedules​

Triggers​

Webhook Triggers​

Processing Webhook Data​

Event Triggers​

Workflows​

Workflow Structure​

Creating a Workflow​

Step Types​

Workflow Variables​

Error Handling​

Execution Limits​

Monitoring Executions​

View Execution Status​

Execution Dashboard​

Webhooks for Execution Events​