User's Guide to Parameterized Agents

guide.md

User's Guide to Parameterized Agents

What Are Parameterized Agents?

Parameterized agents are pre-built agents that you can customize for your specific needs without editing code. Think of them as templates that adapt to your project, client, or context.

Example:
Instead of creating separate agents for each client project, you use one "Requirements Engineer" agent and customize it with:

• Your project name
• Client name
• Programming languages
• Output preferences

---

Why Use Parameterized Agents?

✅ No code editing required - Customize via simple configuration files
✅ Consistent behavior - Same proven agent logic, different context
✅ Easy updates - Agent improvements apply to all your customizations
✅ Quick setup - Configure once per project, use repeatedly
✅ Share-friendly - Team members can use same agents with their own settings

---

Quick Start

1. Set Up Your Workspace

Map your project folder to a workspace:

!add_local_workspace /path/to/your/project --name my_project

Example:

!add_local_workspace C:\Projects\Gatekeeper --name gatekeeper
!add_local_workspace /home/user/acme-api --name acme_api

2. Activate Your Workspace

!set_active_workspace my_project
# or use the shorthand:
!saw my_project

3. Create Customization File

Create a file named .agentc.meta.yaml in your project root:

meta:
  agents:
    # Replace with actual agent key you want to customize
    rita_requirements_engineer:
      project_name: "My Awesome Project"
      client_name: "My Company"
      source_lang: "Python"
      target_lang: "TypeScript"

4. Verify Your Customization

!pp

This shows the rendered prompt with your customizations applied.

---

Finding Customizable Parameters

Check Agent Documentation

Look for a comment block at the top of the agent definition or in documentation:

# PARAMETERIZED AGENT: Rita - Requirements Engineer
#
# Customizable Parameters:
# - project_name: Display name of the project
# - client_name: Client/company name
# - source_lang: Source code language
# - target_lang: Target language for migration
# - code_folder: Relative path to code
# - reference_folder: Output folder for docs

Ask the Agent

Simply ask: "What parameters can I customize in your configuration?"

Use Prompt Preview

Use !pp to see all variables in the render context.

---

Customization File Structure

Basic Structure

meta:
  agents:
    agent_key_name:
      parameter_name: "value"
      another_parameter: "another value"

Example: Single Agent Customization

meta:
  agents:
    rita_requirements_engineer:
      project_name: "Gatekeeper"
      client_name: "ACME Corp"
      source_lang: "VB.Net"
      target_lang: "C#"
      app_target: "modern C# Angular application"
      code_folder: "src"
      reference_folder: "docs"

Example: Multiple Agents

meta:
  agents:
    # Customize Rita
    rita_requirements_engineer:
      project_name: "Gatekeeper"
      client_name: "ACME Corp"
      source_lang: "VB.Net"
    
    # Customize another agent
    pyper_python_code_quality_specialist:
      style_guide: "ACME Python Standards"
      max_line_length: 100

Example: Default Values

Apply settings to all agents:

meta:
  agents:
    default:
      client_name: "ACME Corp"
      company_logo: "acme_logo.png"
      output_format: "Markdown"
    
    # Agent-specific overrides
    rita_requirements_engineer:
      project_name: "Gatekeeper"
      # Inherits client_name and company_logo from default

---

Advanced Customization: Block Overrides

What Are Block Overrides?

Agents use instruction blocks - reusable pieces of their instructions. You can create workspace-specific versions of these blocks to customize agent behavior more deeply.

When to Use Block Overrides

• Custom formatting requirements - Your company's documentation style
• Client-specific guidelines - Special rules for a particular client
• Environment variations - Different instructions for dev/staging/prod
• Language-specific patterns - Programming style guides per language

Creating Block Overrides

1. Find the block path - Usually documented or visible in !pp

   • Example: blocks/common/style_guide

2. Create workspace override:

   your_project_folder/
   └── .agentc/
       └── blocks/
           └── common/
               └── style_guide.md
   

3. Write your custom content:

   # ACME Corp Style Guide
   
   - Use American English spelling
   - Maximum line length: 100 characters
   - Follow PEP 8 for Python code
   - Include copyright headers on all files

4. Reload blocks:

   !lb

5. Verify with prompt preview:

   !pp

Block Override Example

Scenario: You want Rita to use your company's output format.

Standard block location: blocks/process/rev_eng/output_format.md

Your override:

/path/to/project/
└── .agentc/
    └── blocks/
        └── process/
            └── rev_eng/
                └── output_format.md

Your custom format:

## ACME Documentation Format

### File Structure
- Use ACME template: `ACME_{{module_name}}_Analysis.md`
- Include ACME header on all documents
- Tag with project code: {{project_name}}-{{timestamp}}

### Content Requirements
1. Executive Summary (1 page max)
2. Technical Deep Dive
3. Risk Assessment
4. Recommendations
5. ACME Sign-off Section

When Rita includes {{ blocks/process/rev_eng/output_format }}, your version loads automatically!

---

Chat Commands Reference

Command	Shorthand	Purpose
!add_local_workspace {path} --name {name}	-	Map a folder to a workspace
!set_active_workspace {name}	!saw	Set active workspace for session
!load_blocks	!lb	Reload block registry (after changes)
!pp	-	Preview rendered prompt with your customizations

Command Examples

# Add workspace
!add_local_workspace C:\Projects\Gatekeeper --name gatekeeper

# Switch to it
!saw gatekeeper

# Make changes to .agentc.meta.yaml or .agentc/blocks/...

# Reload blocks
!lb

# Verify changes
!pp

---

Real-World Examples

Example 1: Code Review Agent for Multiple Projects

Scenario: You review code for multiple clients, each with different standards.

Setup for Client A:

!add_local_workspace /projects/client-a --name client_a
!saw client_a

Client A's .agentc.meta.yaml:

meta:
  agents:
    code_reviewer:
      client_name: "Client A"
      coding_standard: "Google Style Guide"
      max_complexity: 10
      require_tests: true

Client A's custom style block:

/projects/client-a/.agentc/blocks/review/style_rules.md

Setup for Client B:

!saw client_b

Client B's .agentc.meta.yaml:

meta:
  agents:
    code_reviewer:
      client_name: "Client B"
      coding_standard: "Internal Standard v2.1"
      max_complexity: 15
      require_tests: false

Result: Same agent, different behavior per client!

---

Example 2: Migration Project

Scenario: Migrating VB.Net application to C# Angular.

Workspace setup:

!add_local_workspace C:\Migration\Gatekeeper --name gatekeeper
!saw gatekeeper

.agentc.meta.yaml:

meta:
  agents:
    default:
      project_name: "Gatekeeper"
      client_name: "ACME Corp"
      
    rita_requirements_engineer:
      source_lang: "VB.Net"
      target_lang: "C#"
      app_target: "modern C# Angular application"
      code_folder: "legacy/src"
      reference_folder: "migration_docs"
    
    migration_specialist:
      migration_phase: "phase_1_backend"
      test_coverage_target: "90%"

Custom blocks:

gatekeeper/
├── .agentc.meta.yaml
└── .agentc/
    └── blocks/
        ├── migration/
        │   └── acme_patterns.md     # ACME-specific patterns
        └── testing/
            └── acme_test_policy.md  # ACME test requirements

---

Example 3: Multi-Language Development

Scenario: Working with Python, TypeScript, and Go projects.

.agentc.meta.yaml:

meta:
  agents:
    default:
      company_name: "My Company"
      
    code_assistant:
      primary_language: "Python"
      secondary_languages:
        - "TypeScript"
        - "Go"
      style_guide_url: "https://docs.mycompany.com/style"
      linter_config: ".pylintrc"

Language-specific overrides:

project/
└── .agentc/
    └── blocks/
        ├── languages/
        │   ├── python/
        │   │   └── best_practices.md
        │   ├── typescript/
        │   │   └── best_practices.md
        │   └── go/
        │       └── best_practices.md

Agent automatically uses the right guide based on context!

---

Workflow Tips

Initial Setup (Once per Project)

1. ✅ Create/map workspace: !add_local_workspace
2. ✅ Activate workspace: !saw workspace_name
3. ✅ Create .agentc.meta.yaml with your parameters
4. ✅ Verify with !pp

Daily Use

1. ✅ Start session: !saw workspace_name
2. ✅ Work with agents normally - they use your customizations automatically
3. ✅ Update .agentc.meta.yaml as project evolves
4. ✅ Reload blocks if you change them: !lb

Switching Between Projects

# Morning: Work on Project A
!saw project_a

# Afternoon: Switch to Project B
!saw project_b

All agents automatically adapt to the active workspace!

---

Troubleshooting

Problem: Agent not using my parameters

Solution:

1. Verify workspace is active: !saw workspace_name
2. Check .agentc.meta.yaml is in workspace root
3. Verify agent key matches exactly: !pp to see what's loaded
4. Check YAML syntax (spaces matter!)

Problem: Custom blocks not loading

Solution:

1. Reload blocks: !lb
2. Check path structure: .agentc/blocks/{exact/path/from/original}
3. Verify file extension matches (.md)
4. Use !pp to see which blocks loaded

Problem: Changes not appearing

Solution:

1. After changing .agentc.meta.yaml: Restart chat or reload agent
2. After changing .agentc/blocks/: Run !lb
3. Verify with !pp after changes

Problem: YAML file errors

Solution:

# ❌ Wrong - inconsistent indentation
meta:
  agents:
    my_agent:
     parameter: "value"  # Messed up indent

# ✅ Correct - consistent 2-space indentation
meta:
  agents:
    my_agent:
      parameter: "value"

Use a YAML validator if unsure!

---

Best Practices

1. Document Your Customizations

Add comments to your .agentc.meta.yaml:

meta:
  agents:
    rita_requirements_engineer:
      # Project identification
      project_name: "Gatekeeper"
      client_name: "ACME Corp"
      
      # Migration settings - changed from Python 2024-02-15
      source_lang: "VB.Net"
      target_lang: "C#"
      
      # Folder structure
      code_folder: "src"          # Main source code
      reference_folder: "docs"     # Output documentation

2. Use Sensible Defaults

Only override what's actually different:

meta:
  agents:
    default:
      # Company-wide settings
      company_name: "ACME Corp"
      output_format: "Markdown"
    
    # Only override project-specific details
    rita_requirements_engineer:
      project_name: "Gatekeeper"
      source_lang: "VB.Net"

3. Version Control Your Customizations

✅ DO commit:

• .agentc.meta.yaml
• .agentc/blocks/ custom blocks

❌ DON'T commit:

• Sensitive credentials
• API keys
• Personal preferences

4. Keep Block Overrides Focused

Only override what you need to change:

# ❌ Don't copy entire instruction blocks just to change one line
# ✅ Create minimal override that references the original when possible

5. Test Before Sharing

Before sharing with team:

1. Test with fresh workspace
2. Verify !pp shows expected values
3. Document non-obvious customizations
4. Include setup instructions

---

Configuration Examples

Minimal Configuration

meta:
  agents:
    my_agent:
      project_name: "MyProject"

Comprehensive Configuration

meta:
  agents:
    # Company-wide defaults
    default:
      company_name: "ACME Corp"
      company_logo: "assets/acme_logo.png"
      output_format: "Markdown"
      timezone: "America/New_York"
    
    # Requirements engineer
    rita_requirements_engineer:
      project_name: "Gatekeeper"
      client_name: "ACME Corp"  # Overrides default if needed
      source_lang: "VB.Net"
      target_lang: "C#"
      app_target: "modern C# Angular application"
      code_folder: "src"
      reference_folder: "migration_docs"
      migration_phase: "requirements"
    
    # Code reviewer
    code_reviewer:
      coding_standard: "ACME C# Standard v3.2"
      max_complexity: 12
      require_tests: true
      test_coverage_min: 85
    
    # Migration specialist
    migration_specialist:
      migration_strategy: "phased"
      current_phase: "phase_1_backend"
      test_coverage_target: "90%"
      deployment_env: "staging"

---

Getting Help

Ask the Agent

Most parameterized agents can explain their configuration:

• "What parameters can I customize?"
• "Show me an example configuration"
• "What blocks can I override?"

Check Documentation

Look for:

• Comments in agent YAML files
• designers_guide_parameterized_agents.md
• Agent-specific documentation

Use Prompt Preview

!pp

Shows:

• Current render variables
• Loaded blocks
• Active customizations

---

Summary

Parameterized agents are easy to use:

1. ✅ Map your project folder: !add_local_workspace
2. ✅ Create .agentc.meta.yaml in project root
3. ✅ Customize parameters under meta/agents/{agent_key}
4. ✅ Activate workspace: !saw workspace_name
5. ✅ Verify: !pp
6. ✅ Work normally - agents adapt automatically!

Optional advanced customization:

• Create .agentc/blocks/ overrides for deeper customization
• Reload with !lb after block changes

The benefit: Reuse powerful agents across projects without code duplication!

---

Related Documentation

• For Agent Designers: designers_guide_parameterized_agents.md
• Workspaces: workspace_user_guide.md
• Instruction Blocks: users_guide_instruction_blocks.md