Skip to main content

Creating Templates

Create and contribute your own templates to share with the Xagent community.

Template Structure

Templates are defined as YAML files with the following structure:

Template Fields

Metadata

id (Required)
  • Unique identifier for the template
  • Use kebab-case (e.g., customer-support-agent)
  • Must be unique across all templates
name (Required)
  • Display name shown in the template library
  • Use clear, descriptive names
  • Maximum 200 characters
category (Required)
  • Template category for organization
  • Common categories:
    • Customer Service
    • General & Productivity
    • Finance, LMS & Ops
    • Healthcare & Fitness
    • Security
tags (Optional)
  • List of searchable tags
  • Help users discover your template
  • Use lowercase, hyphenated tags
descriptions (Required)
  • Multi-language descriptions
  • en (English) is required
  • zh (Chinese) is recommended
  • Keep descriptions concise and clear
featured (Optional)
  • Set to true for highlighted templates
  • Default: false
  • Featured templates are shown prominently
author (Optional)
  • Template author or organization
  • Default: “Xagent”
version (Optional)
  • Template version
  • Follow semantic versioning (e.g., “1.0”, “1.1”, “2.0”)
  • Default: “1.0”

Agent Configuration

instructions (Required)
  • System prompt defining the agent’s role and behavior
  • Be specific about what the agent should do
  • Include guidelines for tone, approach, and constraints
skills (Optional)
  • List of pre-built skill IDs
  • Leave empty if no skills needed
  • Default: []
tool_categories (Optional)
  • List of tool categories to enable:
    • basic - Basic tools (web search, calculator)
    • file - File upload and management
    • vision - Image understanding
    • image - Image generation and editing
    • knowledge - Knowledge base operations
    • mcp - MCP protocol tools
    • browser - Browser automation
    • ppt - PowerPoint processing
    • office - Office document processing
    • special_image - Special image processing
  • Default: []
execution_mode (Optional)
  • react - ReAct loop (reasoning → acting)
  • graph - DAG planning-execution
  • Default: "react"

Creating a Template

Step 1: Design Your Template

Before writing the YAML, plan your template:
  1. Identify the use case - What problem does it solve?
  2. Define the agent’s role - What should it do?
  3. Determine required tools - What tools does it need?
  4. Choose execution mode - React or Graph?

Step 2: Create the YAML File

Create a new YAML file with your template definition:

Step 3: Test Your Template

Before contributing, test your template:
  1. Local Testing
    • Add your YAML file to the templates directory
    • Restart Xagent
    • Create an agent from your template
    • Test with various inputs
    • Verify behavior matches expectations
  2. Validation Checklist
    • YAML syntax is valid
    • All required fields are present
    • Instructions are clear and specific
    • Tools work as expected
    • Template solves the intended problem

Contributing Templates

Templates are maintained in the Xagent repository. To contribute your template:

Step 1: Fork the Repository

Step 2: Add Your Template

Place your YAML file in the templates directory:

Step 3: Test Locally

Test your template in your local Xagent instance:
  1. Start Xagent
  2. Go to Build page
  3. Click New Agent
  4. Find your template in the library
  5. Create an agent and test it

Step 4: Submit a Pull Request

PR Guidelines

Title Format
Description Template
Review Process
  • Maintainers will review your template
  • Feedback will be provided if changes are needed
  • Once approved, your template will be merged
  • Templates are released with Xagent updates

Best Practices

Instructions

  • Be Specific - Clearly define the agent’s role and behavior
  • Include Guidelines - Specify tone, approach, and constraints
  • Set Boundaries - Explain what the agent should not do
  • Provide Examples - Include example behaviors in instructions

Tool Selection

  • Minimal Tools - Only enable tools the template needs
  • Clear Purpose - Each tool should have a clear use case
  • Test Tools - Verify tools work as expected

Categories and Tags

  • Choose Appropriate Category - Match existing categories when possible
  • Use Descriptive Tags - Help users discover your template
  • Avoid Over-tagging - 3-5 relevant tags are sufficient

Documentation

  • Clear Descriptions - Explain what the template does
  • Multi-language - Include both English and Chinese
  • Concise - Keep descriptions brief but informative

Template Examples

Simple Template

Advanced Template

Resources

Next Steps