Workspace YAML Basics

Learn the fundamentals of workspace.yml configuration

Workspace YAML Basics

The workspace.yml file is the heart of your Atlas workspace. It defines your agents, signals, jobs, and how they work together. Let’s master the basics of workspace configuration.

File Structure Overview

A workspace.yml file has four main sections:

version: "1.0"  # Required version

workspace:      # Workspace identity
  name: "my-workspace"
  description: "What this workspace does"

agents:         # AI agents definitions
  # Your agents here

signals:        # Event triggers
  # Your signals here  

jobs:           # Workflows
  # Your jobs here

Workspace Identity

Every workspace needs basic identification:

workspace:
  name: "customer-support"
  description: "AI-powered customer support system"

The workspace ID is auto-generated, but you can view it:

atlas workspace info

Defining Agents

Agents are your AI workers. Here’s the basic structure:

agents:
  # Simple agent
  assistant:
    type: "llm"
    model: "claude-3-5-sonnet-20241022"
    purpose: "General assistance"
    prompts:
      system: "You are a helpful assistant."
  
  # More complex agent
  analyst:
    type: "llm"
    model: "claude-3-5-sonnet-20241022"
    description: "Data analysis specialist"
    purpose: "Analyze data and provide insights"
    prompts:
      system: |
        You are a data analyst who:
        - Identifies patterns and trends
        - Provides actionable insights
        - Uses clear visualizations
    config:
      temperature: 0.3
      max_tokens: 2000

Agent Properties

Property	Required	Description
type	Yes	Agent type: “llm”, “system”, or “remote”
model	For LLM	The AI model to use
purpose	Yes	What the agent does
prompts	For LLM	System and user prompts
config	No	Additional configuration

Creating Signals

Signals trigger your jobs:

signals:
  # CLI signal
  analyze:
    provider: "cli"
    description: "Trigger analysis via CLI"
  
  # Webhook signal
  github-push:
    provider: "webhook"
    description: "Triggered by GitHub pushes"
    config:
      path: "/webhooks/github"
      method: "POST"
  
  # Scheduled signal
  daily-report:
    provider: "schedule"
    description: "Daily report at 9 AM"
    config:
      schedule: "0 9 * * *"
      timezone: "America/New_York"

Signal Providers

• cli - Manual triggers from command line
• webhook - HTTP webhook endpoints
• schedule - Cron-based scheduling
• file - File system events
• system - Internal Atlas events

Designing Jobs

Jobs define workflows - how agents respond to signals:

jobs:
  # Simple job
  quick-analysis:
    triggers:
      - signal: "analyze"
    execution:
      agents:
        - id: "analyst"
          input_source: "signal"
  
  # Complex job with multiple agents
  full-pipeline:
    name: "Complete Analysis Pipeline"
    description: "Research, analyze, and report"
    triggers:
      - signal: "analyze"
        condition:
          type: "json_logic"
          logic:
            "==": [{"var": "priority"}, "high"]
    execution:
      strategy: "sequential"
      agents:
        - id: "researcher"
          input_source: "signal"
          task: "Research the topic"
        - id: "analyst"  
          input_source: "previous"
          task: "Analyze findings"
        - id: "reporter"
          input_source: "previous"
          task: "Create report"

Execution Strategies

Sequential - Agents run one after another:

execution:
  strategy: "sequential"
  agents:
    - id: "first"
    - id: "second"  # Gets output from first
    - id: "third"   # Gets output from second

Parallel - Agents run simultaneously:

execution:
  strategy: "parallel"
  agents:
    - id: "agent1"
    - id: "agent2"
    - id: "agent3"

Complete Example

Here’s a complete workspace.yml for a content creation system:

version: "1.0"

workspace:
  name: "content-creator"
  description: "AI-powered content creation workspace"

agents:
  researcher:
    type: "llm"
    model: "claude-3-5-haiku-20241022"
    purpose: "Research topics"
    prompts:
      system: |
        You are a research specialist who:
        - Finds relevant, accurate information
        - Identifies key points and themes
        - Provides sources and citations
  
  writer:
    type: "llm"
    model: "claude-3-5-sonnet-20241022"
    purpose: "Write engaging content"
    prompts:
      system: |
        You are a skilled content writer who:
        - Creates engaging, well-structured content
        - Adapts tone to the audience
        - Follows SEO best practices
    config:
      temperature: 0.7
  
  editor:
    type: "llm"
    model: "claude-3-5-sonnet-20241022"
    purpose: "Edit and improve content"
    prompts:
      system: |
        You are a professional editor who:
        - Improves clarity and flow
        - Fixes grammar and style issues
        - Ensures consistency
        - Preserves the author's voice

signals:
  create-content:
    provider: "cli"
    description: "Create new content"
    schema:
      type: "object"
      properties:
        topic:
          type: "string"
        audience:
          type: "string"
          enum: ["technical", "general", "business"]
        length:
          type: "integer"
          minimum: 100
          maximum: 5000
      required: ["topic", "audience"]

jobs:
  content-pipeline:
    name: "Content Creation Pipeline"
    description: "Research, write, and edit content"
    triggers:
      - signal: "create-content"
    execution:
      strategy: "sequential"
      agents:
        - id: "researcher"
          input_source: "signal"
          task: "Research {topic} for {audience} audience"
        
        - id: "writer"
          input_source: "previous"
          task: "Write a {length}-word article based on research"
          context:
            include_signal: true
        
        - id: "editor"
          input_source: "previous"
          task: "Edit and polish the article"

YAML Best Practices

1. Use Clear Names

# Good
agents:
  customer-support-agent:
  data-analyst:
  report-generator:

# Avoid
agents:
  agent1:
  helper:
  thing:

2. Multi-line Strings

Use | for formatted text:

prompts:
  system: |
    First line
    Second line
    Third line

Use > for wrapped text:

description: >
  This is a long description that
  will be wrapped into a single line
  with spaces between the parts.

3. Comments

Document your configuration:

agents:
  analyzer:
    type: "llm"
    model: "claude-3-5-sonnet-20241022"  # Using Sonnet for balanced performance
    # Note: Temperature is low for consistent analysis
    config:
      temperature: 0.3

4. Environment Variables

Keep secrets safe:

agents:
  api-caller:
    config:
      api_key: "${API_KEY}"  # Read from environment
      endpoint: "${API_ENDPOINT:-https://default.api.com}"  # With default

5. Anchors and Aliases

Reuse configuration:

# Define anchor
default_llm_config: &default_config
  model: "claude-3-5-sonnet-20241022"
  config:
    temperature: 0.7
    max_tokens: 2000

agents:
  writer:
    type: "llm"
    <<: *default_config  # Use anchor
    purpose: "Write content"
  
  editor:
    type: "llm"
    <<: *default_config  # Reuse same config
    purpose: "Edit content"

Validation

Always validate your configuration:

# Validate syntax
atlas config validate

# Test with dry run
atlas signal trigger my-signal --dry-run

Common Patterns

1. Simple Assistant

agents:
  assistant:
    type: "llm"
    model: "claude-3-5-haiku-20241022"
    purpose: "Help with various tasks"
    prompts:
      system: "You are a helpful assistant."

signals:
  help:
    provider: "cli"
    description: "Get help"

jobs:
  assist:
    triggers:
      - signal: "help"
    execution:
      agents:
        - id: "assistant"

2. Pipeline Pattern

jobs:
  pipeline:
    execution:
      strategy: "sequential"
      agents:
        - id: "preprocessor"
          task: "Prepare data"
        - id: "analyzer"
          task: "Analyze prepared data"
        - id: "reporter"
          task: "Create report from analysis"

3. Conditional Execution

jobs:
  smart-handler:
    triggers:
      - signal: "process"
        condition:
          type: "json_logic"
          logic:
            "if": [
              {"==": [{"var": "type"}, "urgent"]},
              "high-priority-job",
              "normal-job"
            ]

Troubleshooting

Common Issues

YAML Syntax Error:

# Wrong - missing quotes
description: This is John's workspace

# Correct
description: "This is John's workspace"

Indentation Error:

# Wrong
agents:
assistant:  # Not indented
  type: "llm"

# Correct  
agents:
  assistant:  # Properly indented
    type: "llm"

Missing Required Fields:

# Wrong - missing type
agents:
  assistant:
    model: "claude-3-5-sonnet-20241022"

# Correct
agents:
  assistant:
    type: "llm"  # Required field
    model: "claude-3-5-sonnet-20241022"

Next Steps

• Learn about Defining Agents
• Explore Creating Signals
• Master Designing Jobs
• Add Tools to Your Workspace