Agent Creator

Systematic framework for designing and configuring AI agents in multiagent systems.

Quick Start

Generate a new agent configuration:

# Orchestrator agent
python scripts/generate_agent.py orchestrator task-coord-001 \
  "Task Coordinator" \
  "Coordinates multi-agent workflows for complex tasks" \
  output/task_coordinator.json

# Specialist agent (requires domain parameter)
python scripts/generate_agent.py specialist code-reviewer-001 \
  "Python Code Reviewer" \
  "Reviews Python code for quality and security" \
  python \
  output/code_reviewer.json

# Other agent types
python scripts/generate_agent.py <type> <id> <name> <description> [domain] [output_file]

Validate configuration:

python scripts/validate_agent.py output/task_coordinator.json

Agent Types

Orchestrator

Purpose: Coordinate multiple agents in complex workflows

When to use:

• Breaking down complex tasks into subtasks
• Delegating work to specialist agents
• Aggregating results from multiple sources
• Managing workflow execution and error recovery

Key capabilities: task_decomposition, agent_selection, result_aggregation, workflow_execution

Specialist

Purpose: Deep expertise in specific domains

When to use:

• Domain-specific operations requiring specialized knowledge
• Tasks needing deep technical expertise
• Operations with strict domain compliance requirements

Key capabilities: Domain-specific analysis, validation, processing

Note: Requires domain parameter (e.g., "python", "finance", "security")

Retrieval

Purpose: Search, retrieve, and synthesize information

When to use:

• Multi-source information gathering
• Research requiring query rewriting and refinement
• Cross-source information synthesis

Key capabilities: semantic_search, multi_hop_retrieval, query_rewriting, source_synthesis

Execution

Purpose: Execute actions in target systems

When to use:

• Performing operations in external systems
• Managing transactional operations
• Implementing rollback and recovery

Key capabilities: action_execution, transaction_management, rollback_handling

Analysis

Purpose: Process and analyze data

When to use:

• Data processing and statistical analysis
• Pattern recognition and anomaly detection
• Generating insights and recommendations

Key capabilities: data_processing, statistical_analysis, pattern_recognition, insight_generation

Validation

Purpose: Quality assurance and compliance checking

When to use:

• Validating outputs against requirements
• Compliance and standards checking
• Quality assurance and error detection

Key capabilities: requirements_validation, compliance_checking, quality_assessment

Configuration Structure

Generated agents use a comprehensive JSON structure with 10 major sections:

1. Identity

{
  "agent_id": "unique-identifier",
  "agent_type": "orchestrator|specialist|retrieval|execution|analysis|validation",
  "name": "Human-readable name",
  "description": "Purpose and capabilities",
  "version": "1.0.0",
  "created_at": "ISO8601 timestamp"
}

2. Metadata

Project context and dependencies:

• Author and tags
• Agent dependencies
• Environment (development/staging/production)

3. Role Definition

Defines agent's role and authority:

• Primary role and domain expertise
• Specific responsibilities
• Behavioral guidelines
• Decision authority scope
• Escalation criteria

4. Capabilities

Technical capabilities and quality standards:

• Core functions
• Supported operations
• Input/output formats
• Quality standards and metrics

5. Tools

Tool definitions with:

• Name and description
• Parameter schemas
• Return types
• Error handling
• Usage examples

6. Communication

Inter-agent communication:

• Input/output protocols and schemas
• Message patterns (request, response, notification, query)
• Coordination with peer/upstream/downstream agents
• Context handoff protocols

7. State Management

State handling configuration:

• State type (stateless/stateful/hybrid)
• Persistence configuration
• Session management
• Short-term and long-term memory

8. Error Handling

Error recovery strategies:

• Error handling strategy (recommend: return_structured_errors)
• Error type definitions
• Recovery patterns
• Retry policies
• Fallback behaviors
• Logging configuration

9. Constraints

Operational boundaries:

• Token budgets and compaction strategies
• Execution time and tool call limits
• Scope boundaries (allowed/forbidden operations)
• Quality gates (validation, approval, testing)

10. Performance

Performance monitoring and optimization:

• Metrics tracking (completion rate, errors, latency, tokens)
• Performance targets
• Optimization features (caching, parallel execution, batching)

Customizing Generated Agents

Generated configurations provide complete structures with sensible defaults. Customize by editing the JSON:

Essential Customizations

1. Metadata

"metadata": {
  "author": "your-team",
  "tags": ["backend", "api", "production"],
  "dependencies": ["retrieval-agent-001"],
  "environment": "production"
}

2. Add Tools

"tools": [{
  "name": "execute_query",
  "description": "Execute SQL query against database",
  "parameters": {
    "query": {
      "type": "string",
      "required": true,
      "description": "SQL SELECT statement"
    },
    "limit": {
      "type": "integer",
      "default": 100
    }
  },
  "returns": {"type": "array"},
  "errors": {
    "InvalidQuery": "SQL syntax error",
    "Timeout": "Query exceeded time limit"
  },
  "example": {
    "input": {"query": "SELECT * FROM users LIMIT 10"},
    "output": [{"user_id": 1, "name": "Alice"}]
  }
}]

3. Configure State Management

"state_management": {
  "state_type": "stateful",
  "persistence": {
    "enabled": true,
    "storage_backend": "redis",
    "retention_policy": "7d"
  },
  "session_management": {
    "enabled": true,
    "timeout": 3600,
    "cleanup_policy": "auto"
  }
}

4. Set Token Budgets

"constraints": {
  "token_budget": {
    "max_tokens": 50000,
    "warning_threshold": 40000,
    "compaction_strategy": "preserve_recent_and_critical"
  },
  "execution_limits": {
    "max_execution_time": 300000,
    "max_tool_calls": 20,
    "max_retries": 3
  },
  "scope_boundaries": {
    "allowed_operations": ["read", "analyze", "report"],
    "forbidden_operations": ["delete", "modify"],
    "data_access_rules": ["read_only"]
  }
}

5. Define Agent Coordination

"communication": {
  "coordination": {
    "peer_agents": ["analysis-agent-002"],
    "upstream_agents": ["orchestrator-001"],
    "downstream_agents": ["execution-agent-001", "validation-agent-001"],
    "handoff_protocol": {
      "required_context": ["task_id", "input_data", "constraints"],
      "response_format": "structured_result"
    }
  }
}

Workflows

Creating a New Agent

1. Generate base configuration:

   python scripts/generate_agent.py <type> <id> <name> <description> [domain] output.json
   

2. Validate structure:

   python scripts/validate_agent.py output.json
   

3. Customize the JSON for your specific needs:

   • Add specific tools with full documentation
   • Configure state management if stateful
   • Set token budgets and constraints
   • Define communication protocols
   • Specify coordination with other agents

4. Re-validate after customization

5. Integrate into your agent system

Building a Multi-Agent System

1. Identify agent roles needed for your use case

2. Create orchestrator agent first:

   python scripts/generate_agent.py orchestrator main-coord "Main Coordinator" \
     "Coordinates all agents in the system" coordinator.json
   

3. Create specialist agents for each domain:

   python scripts/generate_agent.py specialist data-analyst "Data Analyst" \
     "Analyzes business data" analytics analyst.json
   

4. Create supporting agents (retrieval, execution, validation):

   python scripts/generate_agent.py retrieval info-retrieval "Information Retriever" \
     "Gathers information from multiple sources" retrieval.json
   

5. Configure coordination in each agent's communication.coordination section:

   • Set upstream_agents (who delegates to this agent)
   • Set downstream_agents (who this agent delegates to)
   • Set peer_agents (same-level collaborators)
   • Define handoff_protocol (what context to pass)

6. Validate all agents

7. Test agent interactions before deployment

Best Practices

Agent Design

1. Single Responsibility: Each agent should have one clear purpose

• ✅ "Python Code Reviewer" - specific and focused
• ❌ "Code Reviewer and Deployer" - multiple responsibilities

2. Clear Boundaries: Define what the agent can and cannot do

• Set explicit allowed_operations and forbidden_operations
• Define data access rules
• Specify decision authority scope

3. Explicit Communication: Define protocols clearly

• Specify input/output schemas
• Document message patterns
• Define handoff protocols for agent coordination

4. Error Recovery: Always plan for failures

• Use return_structured_errors strategy
• Define recovery patterns for common errors
• Configure retry policies appropriately
• Implement fallback behaviors

5. Token Awareness: Respect context limits

• Set realistic token budgets
• Define warning thresholds (typically 80%)
• Specify compaction strategies
• Monitor token usage in performance metrics

Configuration Quality

Essential Fields to Populate:

• ✅ role_definition.responsibilities - be specific
• ✅ capabilities.core_functions - list all key capabilities
• ✅ tools - full documentation with examples for each tool
• ✅ constraints.token_budget - set realistic limits
• ✅ constraints.scope_boundaries - define what agent can do
• ✅ communication.coordination - specify agent relationships
• ✅ error_handling.retry_policy - configure retry behavior
• ✅ performance.targets - set measurable goals

Optional but Recommended:

• metadata.tags - for categorization
• metadata.dependencies - for dependency tracking
• state_management - if agent needs persistence
• communication.protocols.input.schema - for validation
• error_handling.recovery_patterns - for common errors

Tool Documentation

Every tool must include:

1. Clear name: Verb-based (e.g., execute_query, validate_schema)
2. When to use: Context for tool selection
3. Complete parameters: Type, required/optional, defaults, descriptions
4. Return specification: Type and structure
5. Error documentation: All possible error types
6. Concrete example: Real input and output

Multi-Agent Coordination

Orchestrator Pattern:

• Orchestrator delegates to specialists
• Specialists return results to orchestrator
• Orchestrator aggregates and returns final result

Pipeline Pattern:

• Agent A outputs to Agent B
• Agent B outputs to Agent C
• Final agent returns result

Consensus Pattern:

• Multiple peer agents process same input
• Results aggregated or voted on
• Best result selected or consensus reached

Reference Documentation

Complete schema reference: See references/schema.md for detailed field-by-field documentation

Example templates: See assets/templates/ for complete examples of each agent type

Validation

The validation script checks:

• ✅ Required fields present
• ✅ Valid agent_type
• ✅ Semantic versioning format
• ✅ Role definition completeness
• ✅ Capability specifications
• ✅ Tool documentation quality
• ✅ Error handling strategy
• ✅ Performance target reasonableness

Run validation:

python scripts/validate_agent.py your_agent.json

Validation returns:

• Errors: Must fix before deployment
• Warnings: Should address for production quality
• Info: Optional improvements

Integration with Other Skills

Use prompt-engineering for:

• Crafting agent system prompts
• Designing tool documentation format
• Creating few-shot examples
• Context management strategies

Use task-decomposition-planning for:

• Breaking down agent responsibilities
• Creating Epic → Story → Subtask hierarchies
• Token budget allocation across tasks
• Dependency identification

Use requirements-ac-writer for:

• Defining agent acceptance criteria
• Creating Given-When-Then scenarios
• Documenting agent requirements

Quick Reference

Generation Commands

# Orchestrator
generate_agent.py orchestrator <id> <name> <description> [output.json]

# Specialist (requires domain)
generate_agent.py specialist <id> <name> <description> <domain> [output.json]

# Retrieval/Execution/Analysis/Validation
generate_agent.py <type> <id> <name> <description> [output.json]

Agent Types

• orchestrator → Workflow coordination
• specialist → Domain expertise
• retrieval → Information gathering
• execution → Action execution
• analysis → Data processing
• validation → Quality assurance

Key Sections to Customize

1. metadata - Author, tags, dependencies
2. tools - Add tool definitions
3. communication.coordination - Agent relationships
4. state_management - If stateful
5. constraints.token_budget - Set limits
6. constraints.scope_boundaries - Define scope
7. performance.targets - Set goals

Best Practices Checklist

• Single, focused responsibility
• Clear decision authority
• Complete tool documentation
• Token budget configured
• Scope boundaries defined
• Error recovery patterns
• Communication protocols specified
• Performance targets set
• Validation passing