Quick Start

Prerequisites

Ensure you have these installed:

Docker and Docker Compose - For running services
Bun - As runtime for your workflow
Compozy CLI - For initializing and managing your project

Initialize a new project

Run compozy init to generate a new project

compozy init hello-world
cd hello-world

Configure your project

Update `compozy.yaml` with basic configuration

compozy.yaml

name: hello-world
version: "0.1.0"
description: A simple greeting workflow

workflows:
  - source: ./workflows/main.yaml

models:
  - provider: openai
    model: gpt-4.1-2025-04-14
    api_key: "{{ .env.OPENAI_API_KEY }}"

runtime:
  type: bun
  entrypoint: "./entrypoint.ts"
  permissions:
    - --allow-read
    - --allow-net
    - --allow-write

autoload:
  enabled: true
  strict: true
  include:
    - "agents/*.yaml"
    - "tools/*.yaml"
  exclude:
    - "**/*~"
    - "**/*.bak"
    - "**/*.tmp"

Environment Variables

Create a `.env` file with your API key

.env

OPENAI_API_KEY=your_openai_api_key_here

Create a simple tool

Create a tool that generates personalized greetings

greeting_tool.ts

interface GreetingInput {
  name: string;
  style?: string;
}

interface GreetingOutput {
  message: string;
  timestamp: string;
}

export async function greetingTool({ input }: { input: GreetingInput }): Promise<GreetingOutput> {
  const { name, style = "friendly" } = input;
  const styles = {
    friendly: `Hello there, ${name}! Hope you're having a great day!`,
    formal: `Good day, ${name}. It's a pleasure to meet you.`,
    casual: `Hey ${name}! What's up?`,
    enthusiastic: `${name}! So excited to meet you! 🎉`
  };

  const message = styles[style as keyof typeof styles] || styles.friendly;
  return {
    message,
    timestamp: new Date().toISOString()
  };
}

Create the runtime entrypoint:

entrypoint.ts

import { greetingTool } from "./greeting_tool.ts";

export default {
  "greeting_tool": greetingTool,
}

Create your workflow

Define a simple workflow that generates personalized greetings

workflows/main.yaml

id: hello-world
version: 0.1.0
description: Generate personalized greetings

schemas:
  - id: greeting_input
    type: object
    properties:
      name:
        type: string
        description: The person's name to greet
      style:
        type: string
        description: Greeting style (friendly, formal, casual, enthusiastic)
        default: friendly
    required:
      - name
      - style

config:
  input:
    $ref: schemas.#(id=="greeting_input")

tools:
  - id: greeting_tool
    description: Generate personalized greetings
    input:
      $ref: schemas.#(id=="greeting_input")

agents:
  - id: greeter
    config:
      $ref: global::models.#(provider=="openai")
    instructions: |
      You are a friendly assistant that creates personalized greetings.
      Use the greeting tool to generate an appropriate greeting, then enhance it with a thoughtful message.
    tools:
      - $ref: local::tools.#(id=="greeting_tool")
    actions:
      - id: create_greeting
        prompt: |
          Please create a greeting for {{ .workflow.input.name }} using the {{ .workflow.input.style }} style.
          After generating the greeting, add a brief, personalized message to make it more engaging.

tasks:
  - id: greet
    type: basic
    $use: agent(local::agents.#(id=="greeter"))
    action: create_greeting
    final: true

outputs:
  greeting: "{{ .tasks.greet.output }}"
  user: "{{ .workflow.input.name }}"
  style: "{{ .workflow.input.style }}"

Test your workflow

Start the development server and test your workflow

# Start the development server
compozy dev

Your server will be running at http://localhost:5001.

test.http

@baseUrl = http://localhost:5001/api/v0
@workflowId = main-workflow

### Execute the workflow with friendly greeting
POST {{baseUrl}}/workflows/{{workflowId}}/executions
Content-Type: application/json

{
  "input": {
    "name": "Alice",
    "style": "friendly"
  }
}

### Execute with formal greeting
POST {{baseUrl}}/workflows/{{workflowId}}/executions
Content-Type: application/json

{
  "input": {
    "name": "Bob",
    "style": "formal"
  }
}

### Check execution status (replace {execution_id} with actual ID)
@execId = {{exec.response.body.data.exec_id}}
GET {{baseUrl}}/executions/{{execId}}

View Results

Your workflow will return something like:

{
  "execution_id": "exec_123456",
  "status": "completed",
  "outputs": {
    "greeting": "Hello there, Alice! Hope you're having a great day! I'm delighted to meet you and I hope this greeting brings a smile to your face. Welcome to the wonderful world of Compozy workflows!",
    "user": "Alice",
    "style": "friendly"
  }
}

Behind the Scenes

Here's what happens when you execute this simple workflow:

Loading diagram...

1
HTTP API Layer
The WorkflowController receives your request at /api/v0/workflows/main-workflow/executions
2
Input Validation
The system validates that the required name field is provided and the optional style field is valid
3
Temporal Workflow Engine
Provides durable execution that survives crashes and manages the workflow lifecycle
4
Task Execution
The single greet task runs with the greeter agent, which uses the greeting tool to generate a response
5
Agent Intelligence
GPT-4.1 receives the greeting instructions and autonomously calls the greeting tool, then enhances the response
6
Tool Execution
The greeting tool runs in the sandboxed Bun runtime and returns a structured response

Key Benefits

Infrastructure as Code for AI

Replace months of custom development with declarative YAML workflows that handle orchestration, state, and scaling automatically

Multi-Model Orchestration

Seamlessly coordinate OpenAI, Anthropic, Google, Groq, and Ollama models in unified workflows with automatic failover

8 Powerful Task Types

Build complex workflows with Basic, Parallel, Collection, Router, Composite, Wait, Signal, and Aggregate task patterns

Token-Aware Memory

Intelligent conversation memory with automatic summarization, PII filtering, and token optimization for cost control

Secure Tool Execution

Run TypeScript tools in sandboxed Bun runtime, integrate HTTP APIs, or connect external MCP servers safely

Built for Production

Temporal-powered durability, automatic retries, comprehensive monitoring, and enterprise-grade reliability out of the box

Next Steps

Congratulations! You've built your first Compozy workflow. This simple example demonstrates the core concepts of agents, tools, and workflows working together.