Debug Agents - Ensemble Edge

Starter Kit - Ships with your template. You own it - modify freely.

Debug agents are utility agents designed to help you test, inspect, and debug your Conductor workflows. These agents are particularly useful during development to understand data flow, test error handling, and validate transformations.

Echo Agent

The echo agent returns its input unchanged, making it perfect for debugging data transformations and inspecting what data reaches an agent after flowing through your ensemble.

Description

Returns input unchanged - useful for debugging flows and inspecting what data reaches an agent after transformations.

Source

agents/debug/echo/echo.yaml

Input Schema

{
  "type": "object",
  "properties": {
    "data": {
      "description": "Any data to echo back"
    }
  }
}

The data field accepts any type - objects, strings, arrays, numbers, etc.

Output Schema

{
  "type": "object",
  "properties": {
    "echo": {
      "description": "The input data unchanged"
    },
    "receivedAt": {
      "type": "string",
      "description": "ISO timestamp when data was received"
    },
    "inputType": {
      "type": "string",
      "description": "JavaScript typeof the input data"
    }
  }
}

Configuration

name: echo
version: 1.0.0
operation: code
handler: ./echo.ts
tags:
  - debug
  - utility

Examples

Echo an Object

flow:
  - name: inspect-data
    agent: echo
    input:
      data: { name: "test", value: 123 }

Output:

{
  "echo": { "name": "test", "value": 123 },
  "receivedAt": "2025-01-15T10:30:00Z",
  "inputType": "object"
}

Echo a String

flow:
  - name: inspect-message
    agent: echo
    input:
      data: "Hello, World!"

Output:

{
  "echo": "Hello, World!",
  "receivedAt": "2025-01-15T10:30:00Z",
  "inputType": "string"
}

Debug Data Transformation

flow:
  - name: transform
    agent: data-processor
    input: { raw: ${input.data} }

  - name: inspect-transformation
    agent: echo
    input:
      data: ${transform.output}

Use Cases

Inspect Transformations: See exactly what data looks like after processing
Validate Flow Logic: Confirm data reaches agents as expected
Debug Type Issues: Check the JavaScript type of data
Test Conditional Logic: Verify data before conditions evaluate

Delay Agent

The delay agent introduces artificial delays before returning, making it essential for testing timeout handling, loading states, concurrent execution, and rate limiting behavior.

Description

Adds artificial delay before returning. Useful for testing timeout handling, loading states in UI, concurrent flow behavior, and rate limiting responses.

Source

agents/debug/delay/delay.yaml

Input Schema

{
  "type": "object",
  "properties": {
    "ms": {
      "type": "number",
      "description": "Delay in milliseconds (max 10000)",
      "default": 1000,
      "minimum": 0,
      "maximum": 10000
    },
    "passthrough": {
      "description": "Data to return after delay"
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "delayed": {
      "type": "boolean",
      "description": "Whether delay was applied"
    },
    "actualDelayMs": {
      "type": "number",
      "description": "Actual delay time in milliseconds"
    },
    "passthrough": {
      "description": "The passthrough data unchanged"
    }
  }
}

Configuration

name: delay
version: 1.0.0
operation: code
handler: ./delay.ts
tags:
  - debug
  - utility
  - testing

Examples

Simple Delay

flow:
  - name: wait
    agent: delay
    input:
      ms: 500

Output:

{
  "delayed": true,
  "actualDelayMs": 500
}

Delay with Data Passthrough

flow:
  - name: simulate-slow-api
    agent: delay
    input:
      ms: 1000
      passthrough: { userId: "123", action: "test" }

Output:

{
  "delayed": true,
  "actualDelayMs": 1000,
  "passthrough": { "userId": "123", "action": "test" }
}

Test Timeout Handling

flow:
  - name: slow-operation
    agent: delay
    input:
      ms: 5000
    timeout: 3000  # Will timeout after 3 seconds

  - name: handle-timeout
    condition: ${slow-operation.failed}
    agent: fallback-handler

Test Concurrent Execution

flow:
  # These run in parallel - observe timing
  - name: task-a
    agent: delay
    input: { ms: 1000, passthrough: { task: "A" } }

  - name: task-b
    agent: delay
    input: { ms: 500, passthrough: { task: "B" } }

  - name: task-c
    agent: delay
    input: { ms: 1500, passthrough: { task: "C" } }

  # This waits for all above to complete
  - name: collect-results
    agent: aggregator
    input:
      results:
        - ${task-a.output}
        - ${task-b.output}
        - ${task-c.output}

Use Cases

Test Timeouts: Verify timeout configuration works correctly
Simulate Slow APIs: Test how your ensemble handles slow external services
Loading State Testing: Test UI loading indicators
Rate Limiting: Test behavior when services are rate-limited
Concurrent Flow Testing: Understand parallel execution timing
Retry Logic: Test backoff strategies with artificial delays

Inspect Context Agent

The inspect-context agent returns information about the current execution context, including auth state, headers, environment variables, and Cloudflare bindings.

Security Critical: Do NOT expose this agent on public endpoints in production. It may reveal internal state, configuration, environment variables, authentication details, and system bindings that should remain private.

Description

Inspects and returns information about the current execution context. Useful for debugging auth propagation, headers, and environment variables.

Source

agents/debug/inspect-context/inspect-context.yaml

Input Schema

{
  "type": "object",
  "properties": {
    "includeEnv": {
      "type": "boolean",
      "default": false,
      "description": "Include env var keys (values redacted)"
    },
    "includeAuth": {
      "type": "boolean",
      "default": true,
      "description": "Include auth context"
    },
    "includeHeaders": {
      "type": "boolean",
      "default": true,
      "description": "Include request headers (auth headers redacted)"
    },
    "includeBindings": {
      "type": "boolean",
      "default": false,
      "description": "Include available Cloudflare bindings"
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "context": {
      "type": "object",
      "properties": {
        "timestamp": {
          "type": "string"
        },
        "executionId": {
          "type": "string"
        },
        "requestId": {
          "type": "string"
        },
        "auth": {
          "type": "object"
        },
        "headers": {
          "type": "object"
        },
        "bindings": {
          "type": "array"
        },
        "env": {
          "type": "object"
        }
      }
    }
  }
}

Configuration

name: inspect-context
version: 1.0.0
operation: code
handler: ./inspect-context.ts
tags:
  - debug
  - diagnostic
  - security-sensitive

Examples

Basic Context Inspection

flow:
  - name: check-context
    agent: inspect-context
    input: {}

Output:

{
  "context": {
    "timestamp": "2025-01-15T10:30:00Z",
    "executionId": "exec_abc123",
    "auth": {
      "authenticated": true,
      "userId": "user_123"
    },
    "headers": {
      "content-type": "application/json",
      "user-agent": "Mozilla/5.0..."
    }
  }
}

Full Inspection (Development Only)

flow:
  - name: full-diagnostic
    agent: inspect-context
    input:
      includeEnv: true
      includeAuth: true
      includeHeaders: true
      includeBindings: true

Debug Auth Propagation

flow:
  - name: verify-auth
    agent: inspect-context
    input:
      includeAuth: true
      includeHeaders: true

  - name: check-authenticated
    condition: ${verify-auth.output.context.auth.authenticated}
    agent: protected-operation

Safe Development Ensemble

name: dev-diagnostics
description: Development-only diagnostic ensemble

trigger:
  - type: http
    path: /dev/diagnostics
    methods: [GET]
    public: false  # Require authentication
    # Add additional auth checks in production

flow:
  - name: check-environment
    condition: ${env.ENVIRONMENT === 'development'}
    agent: inspect-context
    input:
      includeEnv: true
      includeAuth: true
      includeHeaders: true
      includeBindings: true

  - name: block-production
    condition: ${env.ENVIRONMENT !== 'development'}
    operation: code
    handler: |
      return {
        error: "Diagnostics disabled in production",
        status: 403
      }

output:
  - when: ${check-environment.executed}
    status: 200
    body: ${check-environment.output}

  - when: ${block-production.executed}
    status: 403
    body: ${block-production.output}

Use Cases

Debug Authentication: Verify auth tokens are propagated correctly
Inspect Headers: Check what headers reach your ensemble
Environment Validation: Confirm environment variables are set
Binding Discovery: See what Cloudflare bindings are available
Request Debugging: Understand the complete request context
Integration Testing: Validate external service auth headers

Security Considerations

Production Security Checklist:

Never expose inspect-context on public endpoints
Always require authentication for diagnostic endpoints
Use environment checks to disable in production
Redact sensitive values before logging
Consider removing or disabling in production builds
Review output before sharing logs or screenshots
Use conditional execution based on environment
Implement IP whitelisting for diagnostic endpoints
Add audit logging when context inspection occurs
Consider time-based access tokens for debug endpoints

Recommended Protection Pattern

flow:
  # Always check environment first
  - name: verify-dev-environment
    operation: code
    handler: |
      if (env.ENVIRONMENT !== 'development') {
        throw new Error('Diagnostics disabled');
      }
      return { allowed: true };

  - name: inspect
    condition: ${verify-dev-environment.success}
    agent: inspect-context
    input:
      includeEnv: false  # Keep false by default
      includeAuth: true
      includeHeaders: true
      includeBindings: false  # Keep false by default

Common Debug Patterns

Pipeline Inspection

Insert echo agents between pipeline stages to inspect data transformations:

flow:
  - name: fetch-data
    agent: api-fetcher
    input: { url: ${input.apiUrl} }

  - name: inspect-raw
    agent: echo
    input: { data: ${fetch-data.output} }

  - name: transform
    agent: data-transformer
    input: { raw: ${fetch-data.output} }

  - name: inspect-transformed
    agent: echo
    input: { data: ${transform.output} }

  - name: save
    agent: storage-writer
    input: { data: ${transform.output} }

Timeout Testing

Test different timeout scenarios systematically:

flow:
  - name: test-fast
    agent: delay
    input: { ms: 100 }
    timeout: 1000

  - name: test-medium
    agent: delay
    input: { ms: 500 }
    timeout: 1000

  - name: test-slow
    agent: delay
    input: { ms: 2000 }
    timeout: 1000  # Will timeout

  - name: handle-timeout
    condition: ${test-slow.failed}
    agent: timeout-handler

Context Validation

Verify execution context before sensitive operations:

flow:
  - name: verify-context
    agent: inspect-context
    input:
      includeAuth: true
      includeHeaders: true

  - name: check-permissions
    operation: code
    handler: |
      const ctx = ${verify-context.output.context};
      if (!ctx.auth.authenticated) {
        throw new Error('Not authenticated');
      }
      if (!ctx.auth.permissions.includes('admin')) {
        throw new Error('Insufficient permissions');
      }
      return { authorized: true };

  - name: admin-operation
    condition: ${check-permissions.success}
    agent: sensitive-operation

Operations Reference

Learn about all available operations

Flow Control

Master conditions and flow patterns

Writing Ensembles

Handle failures and implement fallbacks

Testing & Observability

Write tests for your workflows

​Echo Agent

​Description

​Source

​Input Schema

​Output Schema

​Configuration

​Examples

​Echo an Object

​Echo a String

​Debug Data Transformation

​Use Cases

​Delay Agent

​Description

​Source

​Input Schema

​Output Schema

​Configuration

​Examples

​Simple Delay

​Delay with Data Passthrough

​Test Timeout Handling

​Test Concurrent Execution

​Use Cases

​Inspect Context Agent

​Description

​Source

​Input Schema

​Output Schema

​Configuration

​Examples

​Basic Context Inspection

​Full Inspection (Development Only)

​Debug Auth Propagation

​Safe Development Ensemble

​Use Cases

​Security Considerations

​Recommended Protection Pattern

​Common Debug Patterns

​Pipeline Inspection

​Timeout Testing

​Context Validation

​Related Resources

Operations Reference

Flow Control

Writing Ensembles

Testing & Observability

Echo Agent

Description

Source

Input Schema

Output Schema

Configuration

Examples

Echo an Object

Echo a String

Debug Data Transformation

Use Cases

Delay Agent

Description

Source

Input Schema

Output Schema

Configuration

Examples

Simple Delay

Delay with Data Passthrough

Test Timeout Handling

Test Concurrent Execution

Use Cases

Inspect Context Agent

Description

Source

Input Schema

Output Schema

Configuration

Examples

Basic Context Inspection

Full Inspection (Development Only)

Debug Auth Propagation

Safe Development Ensemble

Use Cases

Security Considerations

Recommended Protection Pattern

Common Debug Patterns

Pipeline Inspection

Timeout Testing

Context Validation

Related Resources