First Workflow

In this comprehensive tutorial, you'll build a complete AI-powered workflow that demonstrates Compozy's core features. We'll create a Go Code Reviewer that analyzes all Go source files in a directory, showcasing parallel task execution and advanced AI-powered code analysis.

By the end of this tutorial, you'll have a workflow that:

1
Directory Input
Accepts a directory path to scan for Go source files.
2
File Discovery
Lists all .go files within the specified directory.
3
Parallel Analysis
Uses an AI agent to review each file concurrently for maximum efficiency.
4
Report Generation
Creates a detailed Markdown review for each analyzed file.

Prerequisites

Before starting, ensure you have:

Compozy installed and running (Installation Guide)
Basic understanding of Core Concepts
A text editor or IDE
API key for OpenAI API
A directory with Go source files to analyze.

Building the project

Project Setup

Create a new directory and configure your project

Create a new directory for your workflow project:

mkdir go-code-reviewer
cd go-code-reviewer

You'll be creating a project with the following structure:

Project Configuration

Create compozy.yaml to define your project:

compozy.yaml

name: code-reviewer
version: "0.0.1"
description: Workflows to review a Go project using Compozy agents

workflows:
  - source: ./workflows/review.yaml

models:
  - provider: openai
    model: o3-mini
    api_key: "{{ .env.OPENAI_API_KEY }}"

config:
  schedule_to_start_timeout: 5m

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

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

Package Dependencies

Create package.json to define project dependencies. This example uses pre-built Compozy tools.

package.json

{
  "name": "@compozy/example-codereview",
  "version": "0.0.1",
  "description": "Workflows to review a Go project using Compozy agents",
  "private": true,
  "type": "module",
  "main": "./entrypoint.ts",
  "scripts": {
    "build": "echo 'No build step required for Compozy examples'",
    "lint": "oxlint *.ts",
    "type-check": "tsc --noEmit",
    "test": "echo 'No tests configured'",
    "clean": "echo 'No clean step required'"
  },
  "devDependencies": {
    "typescript": "^5.8.0",
    "@types/bun": "latest"
  },
  "dependencies": {
    "@compozy/tool-list-files": "0.0.11",
    "@compozy/tool-read-file": "0.0.11",
    "@compozy/tool-write-file": "0.0.11"
  }
}

Install dependencies:

bun install

Environment Setup

Create a .env file to store your OpenAI API key:

.env

# Get your API key from https://platform.openai.com/api-keys
OPENAI_API_KEY=your_openai_api_key_here

Register Tools

Expose pre-built Compozy tools to your workflow

The Bun runtime entrypoint registers the tools that your workflow will use. This example uses standard tools for file operations.

entrypoint.ts

import { listFiles } from "@compozy/tool-list-files";
import { readFile } from "@compozy/tool-read-file";
import { writeFile } from "@compozy/tool-write-file";

export default {
  list_files: listFiles,
  read_file: readFile,
  write_file: writeFile,
};

Define the Analyzer Agent

Create an AI agent specialized in Go code analysis

Create agents/analyzer.yaml to define the agent that will perform the code review.

agents/analyzer.yaml

resource: agent
id: analyzer
description: Specialized in Go code analysis for performance and best practices
version: 1.0.0

config:
  $ref: global::models.#(provider=="openai")

instructions: |
  You are an expert Go developer and code reviewer with deep knowledge of:
  - Go performance optimization and profiling
  - Go best practices and idiomatic patterns
  - Concurrent programming in Go
  - Memory management and garbage collection
  - Go standard library and ecosystem

  Your role is to analyze Go code and provide detailed, actionable reports.
  Always provide specific, implementable suggestions with code examples when appropriate.
  Focus on practical improvements that will have measurable impact.

tools:
  - id: write_file
    description: Write content to a file
    input:
      type: object
      properties:
        path:
          type: string
          description: The file path to write to
        content:
          type: string
          description: The content to write
      required:
        - path
        - content

actions:
  - id: analyze
    prompt: |-
      Analyze the following Go code file and save the review as a markdown file:

      File: {{ .input.file_path }}

      Content:
      '''go
      {{ .input.content }}
      '''

      You must:
      1. Analyze the code for:
         - Performance optimizations
         - Go best practices violations
         - Potential bugs or issues
         - Memory management concerns
         - Concurrency issues (if applicable)
         - Suggestions for improvement with specific code examples

      2. Create a comprehensive markdown report with the following structure:
         -  # Code Review: [filename]
         -  ## Summary
         -  ## Performance Analysis
         -  ## Best Practices Review
         -  ## Potential Issues
         -  ## Recommendations
         -  ## Code Examples (if applicable)

      3. Use the write_file tool to save the review to: ./reviews/{{ .input.file_path }}.md
         Make sure to replace any forward slashes in the file path with underscores for the output filename.

      4. Return a summary of your findings after saving the review file.

Create the Main Workflow

Orchestrate all components into a cohesive workflow

Create workflows/review.yaml to define the main workflow logic.

workflows/review.yaml

id: review
version: 0.1.0
description: Review Go code for a given directory

schemas:
  - id: review_input
    type: object
    properties:
      directory:
        type: string
        description: The directory to review
    required:
      - directory

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

tools:
  - id: list_files
    description: List all files in the given directory
    input:
      type: object
      properties:
        dir:
          type: string
          description: The directory to list files from
        exclude:
          type: string
          description: Pattern to exclude files (optional)
      required:
        - dir
  - id: read_file
    description: Read the contents of a file
    input:
      type: object
      properties:
        path:
          type: string
          description: The file path to read
      required:
        - path

tasks:
  - id: review
    type: basic
    $use: tool(local::tools.#(id=="list_files"))
    with:
      dir: "{{ .workflow.input.directory }}"
      exclude: "!*.go"
    on_success:
      next: review_files

  - id: review_files
    type: collection
    mode: parallel
    items: "{{ .tasks.review.output.files }}"
    item_var: file
    final: true
    with:
      dir: "{{ .workflow.input.directory }}"
    task:
      id: "process-{{ .index }}"
      type: composite
      tasks:
        - id: read_content
          type: basic
          $use: tool(local::tools.#(id=="read_file"))
          with:
            path: "{{ .input.dir }}/{{ .file }}"

        - id: analyze_content
          type: basic
          $use: agent(resource::agent::#(id=="analyzer"))
          action: analyze
          with:
            file_path: "{{ .input.dir }}/{{ .file }}"
            content: "{{ .tasks.read_content.output.content }}"

Test Your Workflow

Validate the workflow with a sample directory

Create api.http with the following content to test your workflow. You can use a tool like the REST Client extension for VS Code.

api.http

### code-reviewer API Tests
### This file contains HTTP requests to test your Compozy workflows
### Make sure Compozy is running on localhost:5001 before executing these requests

@baseUrl = http://localhost:5001/api/v0
@workflowId = review

### -----------------------------------------------------------------------------
### Execute review workflow
### -----------------------------------------------------------------------------
# @name review
POST {{baseUrl}}/workflows/{{workflowId}}/executions
Content-Type: application/json
Accept: application/json

{
  "input": {
    "directory": "../../engine/schema"
  }
}

### Get execution ID from response
@execId1 = {{review.response.body.data.exec_id}}

### Check execution status
GET {{baseUrl}}/executions/workflows/{{execId1}}
Accept: application/json

Expected Output

After running the workflow, you will find markdown files in the reviews directory, one for each .go file found in the target directory. The content of each file will be a detailed code review generated by the AI agent.

Understanding the Workflow

Your workflow demonstrates several key Compozy concepts:

1
Collection Tasks
The review_files task iterates over the list of files returned by the list_files tool.
2
Parallel Execution
By setting mode: parallel on the collection task, Compozy reviews all files simultaneously for maximum efficiency.
3
Composite Tasks
Each item in the collection is processed by a composite task that first reads the file content and then passes it to the agent for analysis.
4
Agent Actions
A specialized AI agent performs the code analysis using a detailed prompt and a file-writing tool.
5
Autoloading Resources
The compozy.yaml file is configured to automatically load all agent and tool definitions from the agents/ and tools/ directories.

Signal Tasks

Create event-driven workflows with cross-workflow communication

MCP Integration

Connect external services and APIs using Model Context Protocol

Workflow Patterns

Performance Optimization

Scale your workflows with parallel processing and caching

You now have the foundation to build complex AI workflows with Compozy. The patterns you've learned here can be adapted to countless use cases across different industries and applications.

What You'll Build