> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows & Orchestration

> Define and orchestrate multi-step automated processes

## Overview

Workflows enable you to define complex, multi-step automated processes that orchestrate agents, tools, and external services. Built on Temporal, workflows provide reliable, durable execution with automatic retries and error handling.

## Workflows

Workflows are declarative definitions of multi-step processes that can:

* Execute multiple tasks in sequence or parallel
* Coordinate multiple agents
* Handle errors and retries automatically
* Maintain state across long-running operations
* Integrate with external systems

**Key features:**

* **Durability**: Workflows survive crashes and restarts
* **Observability**: Track execution state and history
* **Scheduling**: Run workflows on a schedule or trigger basis
* **Versioning**: Safely update workflow definitions

## Runners

Runners provide the execution infrastructure for workflows and agents. They:

* Execute workflow steps in isolated environments
* Provide compute resources for agent execution
* Handle scaling and resource management
* Support different runtime environments (containers, VMs, etc.)

**Runner types:**

* **Kubernetes runners**: Execute in Kubernetes pods
* **Container runners**: Execute in Docker containers
* **Cloud runners**: Execute in cloud VMs (AWS, GCP, Azure)

## Common Workflow Patterns

### Sequential Workflow

```yaml theme={null}
name: "Deploy Application"
steps:
  - name: "Run Tests"
    agent: "test-runner"
  - name: "Build Docker Image"
    agent: "builder"
  - name: "Deploy to Production"
    agent: "deployer"
    requires: ["Run Tests", "Build Docker Image"]
```

### Parallel Workflow

```yaml theme={null}
name: "Multi-Cloud Deployment"
parallel:
  - name: "Deploy to AWS"
    agent: "aws-deployer"
  - name: "Deploy to GCP"
    agent: "gcp-deployer"
  - name: "Deploy to Azure"
    agent: "azure-deployer"
```

### Event-Driven Workflow

```yaml theme={null}
name: "Incident Response"
trigger:
  type: "webhook"
  source: "alertmanager"
steps:
  - name: "Analyze Alert"
    agent: "analyzer"
  - name: "Take Action"
    agent: "remediator"
  - name: "Notify Team"
    agent: "notifier"
```

## Workflow Management

### Create a Workflow

```bash theme={null}
POST /api/v1/workflows
{
  "name": "Deploy Application",
  "description": "Multi-step deployment workflow",
  "steps": [
    {
      "name": "run-tests",
      "type": "agent",
      "agent_id": "test-agent-uuid"
    },
    {
      "name": "build-image",
      "type": "agent",
      "agent_id": "builder-agent-uuid"
    },
    {
      "name": "deploy",
      "type": "agent",
      "agent_id": "deployer-agent-uuid"
    }
  ],
  "team_id": "team-uuid"
}
```

**Required fields**: `name`
**Note**: Steps are executed sequentially by default

### Start Workflow Execution

```bash theme={null}
POST /api/v1/workflows/{workflow_id}/start
{
  "input": {
    "environment": "production",
    "version": "v1.2.3"
  }
}
```

## Best Practices

1. **Idempotency**: Design workflow steps to be safely retried
2. **Error Handling**: Define explicit error handling and compensation logic
3. **Timeouts**: Set appropriate timeouts for each step
4. **Monitoring**: Use workflow history for debugging and auditing
5. **Versioning**: Version workflows to support safe updates

## Next Steps

Explore the workflow and runner endpoints to learn about creating, executing, and monitoring workflows.