Creating Custom Agent Templates

Learn how to create custom agent templates for your specific document processing needs. Agent templates define how AI processes your documents, what information to extract, and how to structure the results.

# 1. Create template interactively
doclayer agent init

# 2. Follow the prompts
? Agent ID: custom.my-processor
? Display name: My Document Processor
? Category: [custom]
? LLM preference: [mistral/mistral-large]

# 3. Validate and test
doclayer agent validate ./agents/custom/my-processor/manifest.yml
doclayer agent test custom.my-processor --document sample.pdf

What Are Agent Templates?

Agent templates are YAML configuration files that define:

• Processing Steps: Sequential workflow for document analysis
• AI Models: Which models to use for different services (LLM, OCR, embeddings)
• Instructions: Specific prompts and guidelines for the AI
• Tools: Available functions and capabilities
• Output Format: How to structure the extracted data

Template Structure Overview

Every agent template follows this structure:

apiVersion: agent.doclayer.ai/v1
kind: Agent
metadata:
  name: custom.template-name
  displayName: Template Display Name
  version: 1.0.0
  description: What this template does
  category: custom
spec:
  framework: tinyagent
  model_id: mistral/mistral-large
  instructions: |
    Your custom instructions here...
  
  # AI Model Configuration
  models:
    llm: { provider: mistral, model: mistral-large }
    ocr: { provider: mistral, model: mistral-ocr-latest }
    embeddings: { provider: gemini, model: gemini-embedding-exp-04-17 }
    graph_extraction: { provider: gemini, model: gemini-2.5-flash }
    langextract: { provider: gemini, model: gemini-2.5-flash }
  
  # Processing Steps
  graph:
    - id: step1
      prompt: "First processing step..."
    - id: step2
      prompt: "Second processing step..."
  
  # Optional Tools
  tools: []
  
  # Runtime Configuration
  runtime:
    environment: production
    scaling:
      min_instances: 0
      max_instances: 5

Step-by-Step Creation Guide

Method 1: Interactive CLI Creation (Recommended for Beginners)

# Start the interactive template creator
doclayer agent init

# You'll be prompted for:
? Agent ID: custom.invoice-processor
? Display name: Invoice Processor
? Description: Extract and analyze invoice data
? Category: [finance]
? Base template: [finance.invoice-summary]
? LLM preference: [mistral/mistral-large]

# The CLI creates:
✓ ./agents/finance/invoice-processor/manifest.yml
✓ ./agents/finance/invoice-processor/README.md

Method 2: Manual Creation (For Advanced Users)

# 1. Create directory structure
mkdir -p ./agents/custom/my-template
cd ./agents/custom/my-template

# 2. Create manifest.yml (see detailed example below)
vim manifest.yml

# 3. Create README.md
vim README.md

# 4. Validate your template
doclayer agent validate manifest.yml

# 5. Test your template
doclayer agent test custom.my-template --document sample.pdf

Method 3: Copy and Modify Existing Template

# 1. Copy an existing template
cp -r agent-templates/public/legal/legal-qa ./agents/custom/my-legal-agent

# 2. Edit the manifest
vim ./agents/custom/my-legal-agent/manifest.yml

# 3. Update the metadata
# Change: name, displayName, description, etc.

# 4. Modify the processing steps
# Edit: graph, instructions, tools

# 5. Test your changes
doclayer agent validate ./agents/custom/my-legal-agent/manifest.yml

Detailed Manifest Configuration

Metadata Section

metadata:
  name: custom.template-name          # Unique identifier (category.name format)
  displayName: Template Display Name  # Human-readable name
  version: 1.0.0                      # Semantic version
  description: What this template does # Brief description
  category: custom                    # Category (custom, legal, finance, etc.)
  tags: [invoice, processing, custom] # Optional tags for discovery

Model Configuration

Configure which AI models to use for different services:

models:
  llm:                                # Large Language Model
    provider: mistral                 # mistral, gemini, openai
    model: mistral-large              # Specific model ID
    description: "Main reasoning model"
    cost_multiplier: 1.0              # Cost adjustment (optional)
    performance_tier: standard        # standard, fast, accurate
    fallback_enabled: false           # Allow fallbacks (optional)
  
  ocr:                                # Optical Character Recognition
    provider: mistral                 # mistral, gemini
    model: mistral-ocr-latest         # OCR model ID
    description: "Document text extraction"
    cost_multiplier: 1.0
    performance_tier: standard
    fallback_enabled: false
  
  embeddings:                         # Vector Embeddings
    provider: gemini                  # gemini, openai
    model: gemini-embedding-exp-04-17 # Embedding model ID
    description: "Vector embeddings for search"
    cost_multiplier: 0.8              # 20% discount
    performance_tier: standard
    fallback_enabled: false
  
  graph_extraction:                   # Knowledge Graph Extraction
    provider: gemini                  # gemini, mistral
    model: gemini-2.5-flash           # Graph model ID
    description: "Entity and relationship extraction"
    cost_multiplier: 1.0
    performance_tier: standard
    fallback_enabled: false
  
  langextract:                        # Structured Data Extraction
    provider: gemini                  # gemini, mistral
    model: gemini-2.5-flash           # LangExtract model ID
    description: "Structured data extraction"
    cost_multiplier: 1.0
    performance_tier: standard
    fallback_enabled: false

Processing Graph

Define the sequential steps for processing documents:

graph:
  - id: extract                        # Step identifier
    prompt: |                         # Instructions for this step
      Extract the following information from the document:
      - Key entities and names
      - Important dates
      - Financial amounts
      - Key terms and conditions
      
      Return the data as structured JSON.
    
  - id: analyze                        # Second step
    prompt: |
      Analyze the extracted information:
      - Identify any risks or concerns
      - Highlight important clauses
      - Flag missing information
      - Provide recommendations
    
  - id: summarize                      # Final step
    prompt: |
      Create a comprehensive summary:
      - Executive summary
      - Key findings
      - Action items
      - Risk assessment

Instructions Template

Define the overall behavior and context for your agent:

instructions: |
  You are a specialized document processor for [DOCUMENT_TYPE].
  
  Your role is to:
  1. Extract key information accurately
  2. Identify important patterns and relationships
  3. Flag potential issues or risks
  4. Provide actionable insights
  
  Guidelines:
  - Be thorough but concise
  - Focus on accuracy over speed
  - Highlight critical information
  - Provide context for your findings
  
  Output format:
  - Use structured JSON when possible
  - Include confidence scores
  - Provide reasoning for important decisions

Complete Example: Invoice Processor

apiVersion: agent.doclayer.ai/v1
kind: Agent
metadata:
  name: custom.invoice-processor
  displayName: Custom Invoice Processor
  version: 1.0.0
  description: Extract and analyze invoice data with custom business rules
  category: custom
  tags: [invoice, finance, custom, processing]

spec:
  framework: tinyagent
  model_id: mistral/mistral-large
  
  instructions: |
    You are a specialized invoice processor for [COMPANY_NAME].
    
    Your task is to extract and analyze invoice data according to our specific business requirements:
    - Extract vendor information, amounts, dates, and line items
    - Validate tax calculations and compliance
    - Check against our vendor database
    - Flag any anomalies or missing information
    - Provide approval recommendations
    
    Always maintain high accuracy and provide detailed reasoning for your analysis.

  models:
    llm:
      provider: mistral
      model: mistral-large
      description: "Main reasoning model for invoice analysis"
      cost_multiplier: 1.0
      performance_tier: standard
      fallback_enabled: false
    
    ocr:
      provider: mistral
      model: mistral-ocr-latest
      description: "OCR for invoice text extraction"
      cost_multiplier: 1.0
      performance_tier: standard
      fallback_enabled: false
    
    embeddings:
      provider: gemini
      model: gemini-embedding-exp-04-17
      description: "Vector embeddings for vendor matching"
      cost_multiplier: 0.8
      performance_tier: standard
      fallback_enabled: false
    
    graph_extraction:
      provider: gemini
      model: gemini-2.5-flash
      description: "Extract invoice entities and relationships"
      cost_multiplier: 1.0
      performance_tier: standard
      fallback_enabled: false
    
    langextract:
      provider: gemini
      model: gemini-2.5-flash
      description: "Structured data extraction from invoices"
      cost_multiplier: 1.0
      performance_tier: standard
      fallback_enabled: false

  graph:
    - id: extract_basic_info
      prompt: |
        Extract basic invoice information:
        - Invoice number and date
        - Vendor name and address
        - Total amount and currency
        - Payment terms
        - Tax information (VAT/GST numbers and amounts)
        
        Return as structured JSON with confidence scores.
    
    - id: extract_line_items
      prompt: |
        Extract detailed line items:
        - Item descriptions
        - Quantities and unit prices
        - Line totals
        - Tax rates per line
        - Product/service categories
        
        Validate calculations and flag any discrepancies.
    
    - id: validate_compliance
      prompt: |
        Validate invoice compliance:
        - Check required fields are present
        - Verify tax calculations
        - Validate vendor information
        - Check against company policies
        - Flag any compliance issues
        
        Provide detailed compliance report.
    
    - id: business_analysis
      prompt: |
        Perform business analysis:
        - Compare with historical data
        - Check vendor performance
        - Identify cost trends
        - Recommend approval status
        - Suggest process improvements
        
        Provide actionable business insights.
    
    - id: generate_summary
      prompt: |
        Create executive summary:
        - Key financial figures
        - Important findings
        - Approval recommendation
        - Next steps
        - Risk assessment
        
        Format for management review.

  tools:
    - name: vendor_lookup
      type: builtin
      description: "Look up vendor information in company database"
    
    - name: tax_calculator
      type: builtin
      description: "Calculate and validate tax amounts"
    
    - name: policy_checker
      type: builtin
      description: "Check against company policies and limits"

  model_configuration:
    version: 1.6.0
    updated_at: '2025-01-15T00:00:00Z'
    template_driven: true
    service_specific: true
    fallback_enabled: false
    cost_optimization: true

runtime:
  environment: production
  scaling:
    min_instances: 0
    max_instances: 10
  resources:
    memory: 1Gi
    cpu: 500m

Validation and Testing

Validate Your Template

# Validate template syntax and structure
doclayer agent validate ./agents/custom/my-template/manifest.yml

# Expected output:
✓ Template syntax is valid
✓ All required fields present
✓ Model configuration valid
✓ Processing graph valid
✓ Ready for testing

Test Your Template

# Test with sample document
doclayer agent test custom.my-template --document sample.pdf

# Test with specific model
doclayer agent test custom.my-template --document sample.pdf --model mistral/mistral-large

# Test and save results
doclayer agent test custom.my-template --document sample.pdf --output test-results.json

Run Your Template

# Process a real document
doclayer agent run custom.my-template --document real-document.pdf --wait

# Process asynchronously
doclayer agent run custom.my-template --document real-document.pdf
# Check status later
doclayer document status job_12345

Best Practices

Template Design

• Start Simple: Begin with basic extraction, then add complexity
• Clear Instructions: Write specific, actionable prompts
• Test Thoroughly: Validate with various document types
• Document Everything: Include clear descriptions and examples
• Version Control: Use semantic versioning for updates

Model Selection

• Cost vs Performance: Balance accuracy with processing costs
• Consistent Providers: Use same provider across services when possible
• Appropriate Models: Choose models suited to your document type
• Fallback Strategy: Consider when to allow model fallbacks

Error Handling

• Graceful Degradation: Handle missing or malformed data
• Clear Error Messages: Provide helpful feedback for failures
• Validation Steps: Include data validation in your processing graph
• Confidence Scoring: Include confidence levels in outputs

Troubleshooting

Common Issues

Error: Template syntax is invalid
Solution: Check YAML formatting and indentation

Error: Missing required field 'name'
Solution: Ensure all required metadata fields are present

Error: Invalid model configuration
Solution: Verify provider and model combinations are supported

Error: Model not available
Solution: Check if the specified model is accessible

Error: Processing timeout
Solution: Increase timeout_seconds or optimize processing steps

Error: Invalid document format
Solution: Ensure document is supported format (PDF, DOCX, TXT)

Advanced Features

Template Inheritance

Extend existing templates with additional functionality:

# Base template
extends: finance.invoice-summary

# Override specific sections
models:
  llm:
    provider: gemini  # Use Gemini instead of Mistral
    model: gemini-1.5-pro

# Add additional processing steps
graph:
  - id: custom_validation
    prompt: |
      Perform custom business validation:
      - Check against company policies
      - Validate approval limits
      - Flag unusual patterns

Conditional Processing

Add logic-based processing steps:

graph:
  - id: check_amount
    prompt: |
      Check if invoice amount exceeds approval limit
      If amount > $10,000, flag for manager approval
      Return approval_required: true/false
  
  - id: manager_review
    condition: approval_required == true
    prompt: |
      Generate detailed review for manager approval
      Include risk assessment and recommendations

Next Steps