name: string                    # Unique identifier (required)
description: string             # Human-readable description (required)
version: string                 # Semantic version (default: "1.0.0")

llm: string | object            # Reference to LLM config in llm.json
  # Simple: llm: default
  # With override: llm: { name: default, temperature: 0.3 }

prompt:                         # Prompt configuration (required)
  system: string                # System message/instructions
  inputVariables: [string]      # Variables to interpolate

tools:                          # Tools available to agent (optional)
  - mcp:           # MCP server tools
  - vector:         # Vector store search
  - function:    # Custom functions
  - builtin:         # Built-in tools

output:                         # Output formatting (optional)
  format: text | json | structured

metadata:                       # Custom metadata (optional)
  category: string
  tags: [string]

name: math
description: An agent that can calculate Fibonacci numbers
version: "1.0.0"

llm:
  name: default
  temperature: 0.3

prompt:
  system: |
    You are a mathematical assistant specialized in Fibonacci numbers.

    When users ask about Fibonacci numbers:
    1. Parse the index from their query (0-based indexing)
    2. Use the fibonacci function to calculate the result
    3. Return the result in a clear, formatted way
  inputVariables:
    - query

tools:
  - function:fibonacci  # References fibonacci.function.js

output:
  format: text

metadata:
  category: mathematics
  tags:
    - math
    - fibonacci

name: string                    # Unique identifier (required)
description: string             # Human-readable description (required)
version: string                 # Semantic version (default: "1.0.0")

input:                          # Input schema (required)
  schema:
    :
      type: string | number | boolean | array | object
      required: boolean
      default: any
      description: string

steps:                          # Workflow steps (required)
  - id: string                  # Unique step identifier
    agent: string               # Agent name to execute
    input:                      # Input mapping using templates
      : "{{input.field}}"
      : "{{steps.stepId.output}}"
    condition: string           # Optional conditional execution
    retry:                      # Optional retry configuration
      maxAttempts: number
      delay: number
    output:
      key: string

config:                         # Workflow configuration (optional)
  timeout: number               # Total timeout ms (default: 300000)
  onError: stop | continue | retry

output:                         # Output mapping (required)
  : "{{steps.stepId.output}}"

metadata:                       # Custom metadata (optional)
  category: string
  tags: [string]

name: string                    # Unique identifier (required)
description: string             # Human-readable description (required)

source:                         # Data source (required)
  type: directory | file | url
  path: string                  # Path relative to project root
  pattern: string               # Glob pattern for directories
  recursive: boolean            # Recursive search (default: true)

loader:                         # Document loader (required)
  type: text | pdf | csv | json | markdown

splitter:                       # Text chunking (required)
  type: character | recursive | token | markdown
  chunkSize: number             # Characters per chunk (default: 1000)
  chunkOverlap: number          # Overlap between chunks (default: 200)

embedding: string               # Reference to embedding config (default: "default")

store:                          # Vector store backend (required)
  type: memory | chroma
  options:
    path: string                # Storage path (for chroma)
    collectionName: string      # Collection name
    url: string                 # Server URL (for chroma)

search:                         # Search configuration (optional)
  defaultK: number              # Results per search (default: 4)
  scoreThreshold: number        # Minimum similarity (0-1)

export default {
  name: 'function-name',
  description: 'What it does',

  parameters: {
    param1: {
      type: 'number',  // string | number | boolean | array | object | enum
      description: 'Parameter description',
      required: true,
      default: 0,
    },
  },

  execute: async ({ param1 }) => {
    // Your logic here
    return `Result: ${param1}`;
  },
};

export const metadata = {
  name: 'function-name',
  version: '1.0.0',
  author: 'Your Name',
  tags: ['category'],
};

export default {
  name: 'fibonacci',
  description: 'Returns the nth Fibonacci number (0-based indexing)',

  parameters: {
    n: {
      type: 'number',
      description: 'The index (0-based, max 100)',
    },
  },

  execute: async ({ n }) => {
    if (n < 0 || !Number.isInteger(n)) {
      throw new Error('Index must be a non-negative integer');
    }
    if (n > 100) {
      throw new Error('Index too large (max 100)');
    }

    if (n === 0) return 'Fibonacci(0) = 0';
    if (n === 1) return 'Fibonacci(1) = 1';

    let prev = 0, curr = 1;
    for (let i = 2; i <= n; i++) {
      [prev, curr] = [curr, prev + curr];
    }

    return `Fibonacci(${n}) = ${curr}`;
  },
};

{
  "version": "1.0.0",
  "servers": {
    "fetch": {
      "transport": "streamable-http",
      "url": "https://remote.mcpservers.org/fetch/mcp",
      "description": "Web fetch capabilities",
      "timeout": 30000,
      "enabled": true
    }
  },
  "globalOptions": {
    "throwOnLoadError": false,
    "prefixToolNameWithServerName": true,
    "defaultToolTimeout": 30000
  }
}

GET /health

Response:
{
  "status": "ok",
  "timestamp": "2026-01-21T12:00:00.000Z"
}

curl -X POST http://localhost:3000/api/agents/researcher/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "topic": "your topic",
      "context": "additional context"
    }
  }'

{
  "output": "Agent response text",
  "metadata": {
    "tokensUsed": 150,
    "toolCalls": ["fetch", "vector_search"],
    "duration": 1234
  }
}

curl -X POST http://localhost:3000/api/workflows/research-paper/run \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "topic": "research topic",
      "style": "professional"
    }
  }'

curl -X POST http://localhost:3000/api/vectors/knowledge/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "search term",
    "k": 4
  }'

name: math
description: An agent that can calculate Fibonacci numbers
version: "1.0.0"

llm:
  name: default
  temperature: 0.3

prompt:
  system: |
    You are a mathematical assistant.
    Use the fibonacci function to calculate results.
  inputVariables:
    - query

tools:
  - function:fibonacci

output:
  format: text

name: example-workflow
description: A workflow demonstrating multi-agent orchestration
version: "1.0.0"

input:
  schema:
    topic:
      type: string
      required: true
      description: The topic to process

steps:
  - id: get-time
    agent: time
    input:
      timezone: "America/New_York"
    output:
      key: current_time

  - id: search-knowledge
    agent: knowledge
    input:
      query: "{{input.topic}}"
    output:
      key: knowledge_result

  - id: perform-calculation
    agent: math
    input:
      query: "Calculate the 10th Fibonacci number"
    output:
      key: calculation_result

  - id: summarize
    agent: example
    input:
      query: |
        Summarize: {{steps.get-time.output}}
        Topic: {{input.topic}}
        Knowledge: {{steps.search-knowledge.output}}
        Math: {{steps.perform-calculation.output}}
    output:
      key: final_summary

config:
  timeout: 300000
  onError: stop

output:
  timestamp: "{{steps.get-time.output}}"
  knowledge: "{{steps.search-knowledge.output}}"
  calculation: "{{steps.perform-calculation.output}}"
  summary: "{{steps.summarize.output}}"

name: knowledge
description: Knowledge base for semantic search

source:
  type: directory
  path: vectors/sample-data
  pattern: "*.txt"

loader:
  type: text

splitter:
  type: character
  chunkSize: 1000
  chunkOverlap: 200

embedding: default

store:
  type: memory

search:
  defaultK: 4
  scoreThreshold: 0.2