Mkn Constructor

Skill YAML Schema

Skills register capabilities in the SDK/Studio for discoverability. They link reference documents and define entry points (workflows or agents) that users can invoke.

Location: skills/<skill-name>/skill.yml or agent-templates/<template-name>/skill.yml

---

Root Structure

skill:
  name: <string>              # Required. Unique identifier (kebab-case)
  title: <string>             # Required. Human-readable title
  description: <string>       # Required. What this skill does
  version: <string>           # Required. Semantic version
  category: <list>            # Required. Classification tags
  status: <string>            # Required. "available" or "draft"
  domain: <string>            # Required. Repository URL

  references: <list>          # Optional. Linked reference documents
  workflows: <list>           # Optional. Workflow entry points
  agents: <list>              # Optional. Agent entry points

Note: The root key is skill: (singular object), not skills: (array). Each file defines exactly one skill.

---

Field Reference

name (required)

Unique identifier. Used for dispatching the skill via the SDK.

name: "polymarket-sync-events"
name: "mkn-constructor"
name: "adapters-dataset-generate"

title (required)

title: "Polymarket - Sync Events"
title: "Template Constructor"
title: "Adapters - Dataset Generate"

description (required)

description: "Sync sports events from Polymarket to Machina documents."
description: "End-to-end skill for building, validating, and deploying Machina agent-templates and connectors."
description: "Run full dataset pipeline: checkin → generate → annotate → build → checkout. Uses the adapters-dataset-pipeline agent."

version (required)

Semantic versioning.

version: "1.0.0"
version: "2.0.0"

category (required)

Array of classification tags for filtering and grouping in the SDK.

category:
  - "data-acquisition"
  - "prediction-markets"

category:
  - "devops"
  - "templates"

category:
  - "dataset"
  - "fine-tuning"

category:
  - "testing"
  - "fine-tuning"

category:
  - "setup"
  - "devops"

category:
  - "guide"
  - "fine-tuning"

status (required)

status: "available"
status: "draft"

domain (required)

URL of the repository that owns this skill. Used for provenance tracking.

domain: "https://github.com/machina-sports/machina-templates"
domain: "https://github.com/machina-sports/machina-model-template"

---

References

Array of documents linked to the skill. These are imported as documents and become available to the SDK for context.

references:
  - name: <string>            # Required. Document name ("skill-guide", "skill-reference", or "skill-schema")
    title: <string>           # Required. Display title
    filename: <string>        # Required. File path relative to skill directory
    filetype: <string>        # Required. File format
    metadata: <object>        # Required. Categorization metadata

Reference Types

metadata Fields

Examples

Skill guide (main documentation):

references:
  - name: "skill-guide"
    title: "Adapters - Guide"
    filename: "SKILL.md"
    filetype: "markdown"
    metadata:
      category: "skill-guide"
      skill: "adapters-guide"

Skill references (supporting docs):

references:
  - name: "skill-reference"
    title: "Events API"
    filename: "references/events-api.md"
    filetype: "markdown"
    metadata:
      category: "reference"
      skill: "polymarket-sync-events"
      reference_id: "events-api"

  - name: "skill-reference"
    title: "Search"
    filename: "references/search.md"
    filetype: "markdown"
    metadata:
      category: "reference"
      skill: "polymarket-sync-events"
      reference_id: "search"

Skill schemas (YAML entity definitions):

references:
  - name: "skill-schema"
    title: "Schema: Agent"
    filename: "schemas/agent.md"
    filetype: "markdown"
    metadata:
      category: "skill-schema"
      skill: "mkn-constructor"
      reference_id: "schema-agent"

  - name: "skill-schema"
    title: "Schema: Workflow"
    filename: "schemas/workflow.md"
    filetype: "markdown"
    metadata:
      category: "skill-schema"
      skill: "mkn-constructor"
      reference_id: "schema-workflow"

Mixed guide + references + schemas:

references:
  - name: "skill-guide"
    title: "Template Constructor"
    filename: "SKILL.md"
    filetype: "markdown"
    metadata:
      category: "skill-guide"
      skill: "mkn-constructor"

  - name: "skill-reference"
    title: "Install"
    filename: "references/install.md"
    filetype: "markdown"
    metadata:
      category: "reference"
      skill: "mkn-constructor"
      reference_id: "install"

  - name: "skill-schema"
    title: "Schema: Agent"
    filename: "schemas/agent.md"
    filetype: "markdown"
    metadata:
      category: "skill-schema"
      skill: "mkn-constructor"
      reference_id: "schema-agent"

---

Entry Points

Skills expose entry points that users can invoke. There are two types: workflows (dispatch a single workflow) and agents (dispatch an agent that orchestrates multiple workflows). A skill can have one or both, or neither (guide-only skills).

workflows (optional)

Array of workflow entry points. Each dispatches a named workflow.

workflows:
  - name: <string>            # Required. Workflow name to dispatch
    description: <string>     # Required. Short description
    inputs: <object>          # Required. Input expressions with defaults
    outputs: <object>         # Required. Output expressions

Example — single workflow:

workflows:
  - name: "polymarket-sync-events"
    description: "sync-sports-events"
    inputs:
      tag_id: "$.get('tag_id', 1)"
      series_id: "$.get('series_id', '')"
      limit: "$.get('limit', 100)"
      offset: "$.get('offset', 0)"
    outputs:
      workflow-status: "$.get('workflow-status', 'skipped')"

Example — multiple workflows:

workflows:
  - name: "adapters-test-report-workflow"
    description: "run-test-report"
    inputs:
      model_key: "$.get('model_key', 'sbot_classifier')"
      adapter_type: "$.get('adapter_type', 'classifier')"
      system_prompt: "$.get('system_prompt', '')"
    outputs:
      workflow-status: "$.get('workflow-status', 'skipped')"

  - name: "adapters-test-workflow"
    description: "test-single-query"
    inputs:
      message: "$.get('message', 'Quais são os jogos do Flamengo hoje?')"
      model_key: "$.get('model_key', 'sbot_classifier')"
      adapter_type: "$.get('adapter_type', 'classifier')"
    outputs:
      workflow-status: "$.get('workflow-status', 'skipped')"

agents (optional)

Array of agent entry points. Each dispatches a named agent (which orchestrates multiple workflows).

agents:
  - name: <string>            # Required. Agent name to dispatch
    description: <string>     # Required. Short description
    inputs: <object>          # Required. Input expressions with defaults
    outputs: <object>         # Required. Output expressions

Example:

agents:
  - name: "adapters-dataset-pipeline"
    description: "full-dataset-pipeline"
    inputs:
      adapter_type: "$.get('adapter_type', 'classifier')"
      batch_prompts: "$.get('batch_prompts', [])"
      annotate: "$.get('annotate', False)"
      version: "$.get('version', 'v1')"
      n: "$.get('n', 25)"
      val_ratio: "$.get('val_ratio', 0.10)"
      dedup_threshold: "$.get('dedup_threshold', 0.80)"
    outputs:
      workflow-status: "$.get('workflow-status', 'skipped')"

Input/Output Expression Syntax

Inputs and outputs use the same $.get() expression syntax as workflows.

# Simple with default
tag_id: "$.get('tag_id', 1)"

# String default
series_id: "$.get('series_id', '')"

# Boolean default
annotate: "$.get('annotate', False)"

# List default
batch_prompts: "$.get('batch_prompts', [])"

# Float default
val_ratio: "$.get('val_ratio', 0.10)"

# Standard workflow-status output
workflow-status: "$.get('workflow-status', 'skipped')"

---

Pattern Examples

Data Acquisition Skill (workflow + references)

skill:
  name: "polymarket-sync-markets"
  title: "Polymarket - Sync Markets"
  description: "Sync sports prediction markets from Polymarket to Machina documents."
  version: "1.0.0"
  category:
    - "data-acquisition"
    - "prediction-markets"
  status: "available"
  domain: "https://github.com/machina-sports/machina-templates"

  references:
    - name: "skill-reference"
      title: "Market Types"
      filename: "references/market-types.md"
      filetype: "markdown"
      metadata:
        category: "reference"
        skill: "polymarket-sync-markets"
        reference_id: "market-types"

    - name: "skill-reference"
      title: "Pricing API"
      filename: "references/pricing-api.md"
      filetype: "markdown"
      metadata:
        category: "reference"
        skill: "polymarket-sync-markets"
        reference_id: "pricing-api"

  workflows:
    - name: "polymarket-sync-markets"
      description: "sync-sports-markets"
      inputs:
        tag_id: "$.get('tag_id', 1)"
        sports_market_types: "$.get('sports_market_types', '')"
        limit: "$.get('limit', 100)"
        offset: "$.get('offset', 0)"
      outputs:
        workflow-status: "$.get('workflow-status', 'skipped')"

DevOps Skill (many references, no agents)

skill:
  name: "mkn-constructor"
  title: "Template Constructor"
  description: "End-to-end skill for building, validating, and deploying Machina agent-templates and connectors."
  version: "1.0.0"
  category:
    - "devops"
    - "templates"
  status: "available"
  domain: "https://github.com/machina-sports/machina-templates"

  references:
    - name: "skill-reference"
      title: "Init Template"
      filename: "references/init-template.md"
      filetype: "markdown"
      metadata:
        category: "reference"
        skill: "mkn-constructor"
        reference_id: "init-template"

    - name: "skill-reference"
      title: "Create Template"
      filename: "references/create-template.md"
      filetype: "markdown"
      metadata:
        category: "reference"
        skill: "mkn-constructor"
        reference_id: "create-template"

    # ... more references ...

  workflows:
    - name: "mkn-constructor-check-setup"
      description: "check-doc-structure"
      inputs:
        document_name: "$.get('document_name', 'doc-structure')"
      outputs:
        doc-structure: "$.get('doc-structure', {})"
        check-status: "$.get('workflow-status')"

Pipeline Skill (agent entry point)

Uses agents instead of workflows to dispatch an agent that orchestrates a multi-step pipeline.

skill:
  name: "adapters-dataset-pipeline"
  title: "Adapters - Dataset Pipeline"
  description: "Run full dataset pipeline: checkin → generate → annotate → build → checkout."
  version: "1.0.0"
  category:
    - "dataset"
    - "fine-tuning"
  status: "available"
  domain: "https://github.com/machina-sports/machina-model-template"

  references:
    - name: "skill-guide"
      title: "Adapters - Dataset Pipeline"
      filename: "SKILL.md"
      filetype: "markdown"
      metadata:
        category: "skill-guide"
        skill: "adapters-dataset-pipeline"

    - name: "skill-reference"
      title: "Pipeline Flow"
      filename: "references/pipeline-flow.md"
      filetype: "markdown"
      metadata:
        category: "reference"
        skill: "adapters-dataset-pipeline"
        reference_id: "pipeline-flow"

    - name: "skill-reference"
      title: "Adapter Types"
      filename: "references/adapter-types.md"
      filetype: "markdown"
      metadata:
        category: "reference"
        skill: "adapters-dataset-pipeline"
        reference_id: "adapter-types"

  agents:
    - name: "adapters-dataset-pipeline"
      description: "full-dataset-pipeline"
      inputs:
        adapter_type: "$.get('adapter_type', 'classifier')"
        batch_prompts: "$.get('batch_prompts', [])"
        annotate: "$.get('annotate', False)"
        version: "$.get('version', 'v1')"
        n: "$.get('n', 25)"
        val_ratio: "$.get('val_ratio', 0.10)"
        dedup_threshold: "$.get('dedup_threshold', 0.80)"
      outputs:
        workflow-status: "$.get('workflow-status', 'skipped')"

Guide-Only Skill (references only, no entry points)

Documentation skill with no executable entry points.

skill:
  name: "adapters-guide"
  title: "Adapters - Guide"
  description: "Guide for creating a new LoRA adapter end-to-end: setup, dataset pipeline, train, deploy, eval."
  version: "1.0.0"
  category:
    - "guide"
    - "fine-tuning"
  status: "available"
  domain: "https://github.com/machina-sports/machina-model-template"

  references:
    - name: "skill-guide"
      title: "Adapters - Guide"
      filename: "SKILL.md"
      filetype: "markdown"
      metadata:
        category: "skill-guide"
        skill: "adapters-guide"

Setup Skill (references only)

skill:
  name: "adapters-setup"
  title: "Adapters - Setup"
  description: "Install the machina-model-template and verify all components are properly deployed."
  version: "1.0.0"
  category:
    - "setup"
    - "devops"
  status: "available"
  domain: "https://github.com/machina-sports/machina-model-template"

  references:
    - name: "skill-guide"
      title: "Adapters - Setup"
      filename: "SKILL.md"
      filetype: "markdown"
      metadata:
        category: "skill-guide"
        skill: "adapters-setup"

    - name: "skill-reference"
      title: "Installation Guide"
      filename: "references/installation-guide.md"
      filetype: "markdown"
      metadata:
        category: "reference"
        skill: "adapters-setup"
        reference_id: "installation-guide"

    - name: "skill-reference"
      title: "Component Inventory"
      filename: "references/component-inventory.md"
      filetype: "markdown"
      metadata:
        category: "reference"
        skill: "adapters-setup"
        reference_id: "component-inventory"

---

How Skills Are Installed

Skills are registered in the _install.yml manifest as type: skill:

# In _install.yml
datasets:
  # ... connectors, workflows, agents first ...

  - type: skill
    path: skills/sync-markets/skill.yml
  - type: skill
    path: skills/sync-events/skill.yml
  - type: skill
    path: skills/sync-series/skill.yml

Install order: Skills come last in the datasets array (after agents, workflows, connectors, etc.) because they reference entities that must exist first.

---

Directory Structure

Skills live in a skills/ directory with their own references:

skills/<skill-name>/
├── skill.yml              # Skill definition
├── SKILL.md               # Main guide (optional, referenced as skill-guide)
├── references/            # Reference documents
│   ├── events-api.md
│   ├── search.md
│   └── ...
└── schemas/               # Schema files (optional)
    └── ...

---

Naming Conventions

---

Common Mistakes

Analyze

Analyze a Machina template and provide a comprehensive overview of its components, dependencies, and credentials.

Trigger

• "Analyze template", "What's in this template?", "Overview of template"

Process

1. Identify Template Path

Ask user for the template location. Typical structure:

• {repo}/agent-templates/{template-name}/
• {repo}/connectors/{connector-name}/

2. Discover All Files

List all YAML files in the template directory. Note special directories: agents/, workflows/, prompts/, mappings/, scripts/, configs/, setup/, instructions/, documents/.

3. Read Installation Manifest

Read _install.yml and extract setup metadata. See setup.md for field reference.

4. Analyze Components

For each component type, read the relevant schema for field definitions, then extract key information:

Credentials Extraction

Scan all context-variables for values starting with $:

context-variables:
  google-genai:
    api_key: "$TEMP_CONTEXT_VARIABLE_GOOGLE_GENERATIVE_AI_API_KEY"

Deduplicate all $VARIABLE_NAME references to build the Required Credentials list.

Connector-to-Secrets Mapping

Cross-reference discovered connectors with known secret patterns:

5. Generate Report

# Template Analysis: {template-name}

## Overview
| Field | Value |
|-------|-------|
| **Title** | ... |
| **Description** | ... |
| **Version** | ... |
| **Category** | ... |

## Components Summary
| Type | Count | Files |
|------|-------|-------|
| Agents | X | file1.yml, file2.yml |
| Workflows | X | ... |
| Prompts | X | ... |
| Mappings | X | ... |
| Connectors | X | ... |

## Required Credentials
| Variable | Connector | Workflow |
|----------|-----------|----------|
| `$TEMP_...` | connector-name | workflow-name |

## Connectors Used
| Connector | Commands | Workflows |
|-----------|----------|-----------|
| google-genai | invoke_prompt | ... |

## Agents Detail
### {agent-name}
- Type: Orchestrator
- Status: active
- Workflows: N steps

## Workflows Detail
### {workflow-name}
- Tasks: N steps
- Flow: task-1 → task-2 → task-3

## Data Flow Diagram
(ASCII diagram showing agent → workflows → connectors/documents)

## Installation Order
(from _install.yml datasets)

Tips

• Use this skill before installing to understand requirements
• Check required connectors are available in target environment
• Verify secrets are configured before installation
• Look for foreach patterns — they indicate batch processing
• Check condition fields — they show branching logic

Related

• Install — Install analyzed templates
• Trace — Trace specific agent execution chains
• Secrets — Configure required credentials

API

MCP operations for all Machina entities. Covers CRUD, execution, search, and template import.

Environment Selection

Each environment has its own MCP server prefix. Replace {mcp} in examples with the appropriate prefix.

Additional environments (dev, staging, production) depend on the project's MCP configuration. Each project may expose multiple server prefixes following the pattern mcp__{project}-{env}__.

Common Patterns

Search Interface

All search_* operations share the same parameters:

Get by ID or Name

Most get_* and update_* operations accept either:

• item_id — internal ID
• name — entity name (string match)

Execution Queries

Execution search adds:

---

Agent

Schema: agent.md

search_agents

{mcp}search_agents(
    filters={"name": "my-agent"},
    sorters=["name", 1],
    page=1,
    page_size=10,
    fields=["name", "title", "status"]
)

get_agent / get_agent_by_name

{mcp}get_agent(item_id="abc123")
{mcp}get_agent_by_name(name="my-agent")

create_agent

{mcp}create_agent(name="my-agent", config={
    "title": "My Agent",
    "status": "active",
    "config-frequency": 60,
    "context-agent": {"sport": "soccer"},
    "workflows": [...]
})

update_agent

{mcp}update_agent(item_id="abc123", data={"status": "inactive"})
{mcp}update_agent(name="my-agent", data={"config-frequency": 120})

delete_agent

{mcp}delete_agent(item_id="abc123")

execute_agent

Async execution. Returns agent_run_id immediately.

{mcp}execute_agent(
    agent_id="abc123",        # or name="my-agent"
    messages=[{"role": "user", "content": "Hello"}],
    context={"context-agent": {"sport": "soccer"}}
)
# Returns: {"agent_run_id": "run_xyz"}

search_agent_executions

{mcp}search_agent_executions(
    filters={"name": "my-agent"},
    sorters=["date", -1],
    page=1,
    page_size=5,
    expanded=False,
    totals=True
)

get_agent_execution

{mcp}get_agent_execution(
    agent_id="run_xyz",    # the execution/run ID
    compact=False          # False = full details with workflows
)

---

Connector

Schema: connector.md

connector_search

{mcp}connector_search(
    filters={"name": "openai"},
    sorters=["name", 1],
    page=1,
    page_size=10,
    fields=["name", "description", "commands"]
)

connector_retrieve_id / connector_retrieve_args

{mcp}connector_retrieve_id(item_id="abc123")
{mcp}connector_retrieve_args(name="openai")

connector_describe

Returns connector definition with commands and metadata.

{mcp}connector_describe(item_id="abc123")

create_connector

{mcp}create_connector(name="my-connector", config={
    "filename": "my-connector.py",
    "filetype": "pyscript",
    "commands": [{"name": "Do Something", "value": "do_something"}]
})

connector_update

{mcp}connector_update(item_id="abc123", data={...})

delete_connector

{mcp}delete_connector(item_id="abc123")

connector_executor

Execute a connector command directly.

{mcp}connector_executor(item_id="abc123", data={
    "command": "invoke_prompt",
    "inputs": {"api_key": "...", "messages": [...]}
})

connector_endpoint

Call a REST API connector endpoint.

{mcp}connector_endpoint(item_id="abc123", data={
    "endpoint": "/v1/chat/completions",
    "method": "POST",
    "body": {...}
})

---

Document

Schema: document.md

search_documents

{mcp}search_documents(
    filters={"document_name": "sport:Event", "metadata.league": "premier-league"},
    sorters=["date", -1],
    page=1,
    page_size=20,
    document_id="optional-specific-id",
    fields=["title", "content", "metadata"]
)

get_document

{mcp}get_document(
    item_id="abc123",
    fields=["title", "content", "metadata"]
)

create_document

{mcp}create_document(
    name="sport:Event",
    content={"title": "Match A vs B", "data": {...}},
    metadata={"league": "premier-league", "sport": "soccer"}
)

update_document

{mcp}update_document(item_id="abc123", data={
    "content": {"updated": True},
    "metadata": {"status": "processed"}
})

delete_document

{mcp}delete_document(item_id="abc123")

bulk_delete_documents

{mcp}bulk_delete_documents(
    filters={"document_name": "sport:Event", "metadata.status": "expired"},
    batch_size=100
)

---

Mapping

Schema: mapping.md

mapping_search

{mcp}mapping_search(
    filters={"name": "my-mapping"},
    sorters=["name", 1],
    page=1,
    page_size=10
)

retrieve_mapping_id / retrieve_mapping_args

{mcp}retrieve_mapping_id(item_id="abc123")
{mcp}retrieve_mapping_args(name="my-mapping")

create_mapping

{mcp}create_mapping(name="my-mapping", config={
    "output": [{"field": "...", "value": "..."}]
})

update_mapping

{mcp}update_mapping(item_id="abc123", data={...})
{mcp}update_mapping(name="my-mapping", data={...})

delete_mapping

{mcp}delete_mapping(item_id="abc123")

---

Prompt

Schema: prompt.md

search_prompts

{mcp}search_prompts(
    filters={"name": "my-prompt"},
    sorters=["name", 1],
    page=1,
    page_size=10
)

get_prompt_by_id / get_prompt_by_name

{mcp}get_prompt_by_id(item_id="abc123")
{mcp}get_prompt_by_name(name="my-prompt")

create_prompt

{mcp}create_prompt(name="my-prompt", config={
    "prompts": [{"instruction": "..."}],
    "schema": {...}
})

update_prompt

{mcp}update_prompt(item_id="abc123", data={...})
{mcp}update_prompt(name="my-prompt", data={...})

delete_prompt

{mcp}delete_prompt(item_id="abc123")

execute_prompt

{mcp}execute_prompt(
    prompt_id="abc123",    # or name="my-prompt"
    context={"field": "value"}
)

---

Secrets

Reference: secrets.md

create_secrets

One secret at a time. Name must follow TEMP_CONTEXT_VARIABLE_* pattern.

{mcp}create_secrets(
    name="TEMP_CONTEXT_VARIABLE_OPENAI_API_KEY",
    key="sk-..."
)

check_secrets

{mcp}check_secrets(name="TEMP_CONTEXT_VARIABLE_OPENAI_API_KEY")
# Returns: {"status": "success", "message": "Secret ... exists."}

delete_secrets

{mcp}delete_secrets(name="TEMP_CONTEXT_VARIABLE_OPENAI_API_KEY")

---

Skill

Schema: skill.md

Skills have no dedicated CRUD operations. They are managed through the template import system.

Install

Skills are defined in skill.yml and listed in _install.yml with type: skill. They are imported alongside other template components:

# Local import (includes skills defined in _install.yml)
{mcp}import_template_from_local(
    template="skills/my-skill",
    project_path="/app/{repo-name}/skills/my-skill"
)

# Git import
{mcp}import_template_from_git(repositories=[{
    "repo_url": "https://github.com/org/repo",
    "template": "skills/my-skill",
    "branch": "main"
}])

Verify

After import, skill references are stored as documents. Search by skill metadata:

{mcp}search_documents(
    filters={"metadata.skill": "my-skill", "metadata.category": "reference"},
    page=1,
    page_size=10
)

---

System

health_check

{mcp}health_check()

---

Template Import

Reference: install.md

import_template_from_local

Import from Docker volume mount.

{mcp}import_template_from_local(
    template="connectors/openai",
    project_path="/app/{repo-name}/connectors/openai"
)

project_path must point to the Docker-mounted volume path (e.g., /app/{repo-name}/...).

import_template_from_git

Import from Git repository.

{mcp}import_template_from_git(repositories=[
    {
        "repo_url": "https://github.com/org/repo",
        "template": "connectors/openai",
        "branch": "main"
    }
])

import_dataset_direct

Import raw datasets directly.

{mcp}import_dataset_direct(templates=[
    {"name": "doc-name", "type": "document", "content": {...}}
])

get_template_directories

List available templates in a local path.

{mcp}get_template_directories(repo_url="/app/{repo-name}")

get_git_template_directories

List available templates in a Git repository.

{mcp}get_git_template_directories(
    repo_url="https://github.com/org/repo",
    branch="main"
)

---

Workflow

Schema: workflow.md

search_workflows

{mcp}search_workflows(
    filters={"name": "my-workflow"},
    sorters=["name", 1],
    page=1,
    page_size=10
)

get_workflow

{mcp}get_workflow(item_id="abc123")
{mcp}get_workflow(name="my-workflow")

create_workflow

{mcp}create_workflow(name="my-workflow", config={
    "tasks": [...],
    "context-variables": {...}
})

update_workflow

{mcp}update_workflow(item_id="abc123", data={"tasks": [...]})
{mcp}update_workflow(name="my-workflow", data={...})

delete_workflow

{mcp}delete_workflow(item_id="abc123")

execute_workflow

Synchronous execution. Returns result when complete.

{mcp}execute_workflow(
    workflow_id="abc123",    # or name="my-workflow"
    context={"key": "value"}
)

# Resume a specific run:
{mcp}execute_workflow(run_id="run_xyz")

schedule_workflow

{mcp}schedule_workflow(
    workflow_id="abc123",    # or name="my-workflow"
    schedule={
        "type": "cron",
        "expression": "0 */6 * * *",
        "enabled": True
    }
)

search_workflow_executions

{mcp}search_workflow_executions(
    filters={"name": "my-workflow"},
    sorters=["date", -1],
    page=1,
    page_size=5,
    expanded=False,
    totals=True
)

get_workflow_execution

{mcp}get_workflow_execution(
    workflow_id="run_xyz",   # the execution/run ID
    compact=False,
    fields=["name", "status", "execution_time", "tasks"]
)

---

Operation Matrix

Skills are managed via Template Import (import_template_from_local, import_template_from_git).

Related

• Install — Template import procedures
• Secrets — Vault configuration
• Trace — Execution tracing (uses execution APIs)
• Analyze — Template analysis

Trigger

Use this reference when the user mentions: "connector catalog", "list connectors", "available connectors", "connector docs", "which connectors", "connector documentation".

---

Machina Connectors Catalog

Version: 1.0 Last Updated: 2026-01-17 Repository: machina-templates/connectors

Overview

This catalog documents all available connectors in the Machina platform. Connectors are reusable integrations with external services and APIs, used by agents and workflows to access data, generate content, and interact with third-party systems.

Total Connectors: 35 Connector Types:

• PyScript - Python-based connectors with custom logic
• REST API - OpenAPI spec-based REST connectors

Quick Reference Index

By Category

Alphabetical Index

Note: REST connectors use OpenAPI specs - check the .json file in each connector directory for available endpoints. PyScript connectors define commands in their .yml file.

---

Priority Connectors (Detailed Documentation)

The following connectors are documented in detail due to their high usage and importance in the platform.

1. OpenAI (openai)

Type: PyScript Category: AI/LLM Services Location: machina-templates/connectors/openai/

Description: Official OpenAI SDK connector providing access to GPT models, embeddings, and audio transcription via the OpenAI API.

Environment Variables:

• MACHINA_CONTEXT_VARIABLE_OPENAI_API_KEY - OpenAI API key

Commands:

invoke_prompt

Invoke a GPT model for text generation.

Input Fields:

Output:

{
  "status": true,
  "data": "<ChatOpenAI object>",
  "message": "Model loaded."
}

Example Workflow YAML:

- task: llm-generate
  name: Generate content with GPT-4
  connector:
    name: openai
    command: invoke_prompt
  params:
    api_key: $MACHINA_CONTEXT_VARIABLE_OPENAI_API_KEY
    model_name: "gpt-4"

invoke_embedding

Generate embeddings for text.

Input Fields:

Output:

{
  "status": true,
  "data": "<OpenAIEmbeddings object>",
  "message": "Model loaded."
}

transcribe_audio_to_text

Transcribe audio files using Whisper.

Input Fields:

Output:

{
  "status": true,
  "data": "Transcribed text..."
}

---

2. Google GenAI (google-genai)

Type: PyScript Category: AI/LLM Services Location: machina-templates/connectors/google-genai/

Description: Google Gemini models connector supporting text, image, video generation, and web-grounded search.

Environment Variables:

• MACHINA_CONTEXT_VARIABLE_GOOGLE_GENAI_API_KEY - Google GenAI API key

Commands:

invoke_prompt

Generate text using Gemini models.

Input Fields:

Example Workflow YAML:

- task: llm-generate
  name: Generate with Gemini
  connector:
    name: google-genai
    command: invoke_prompt
  params:
    api_key: $MACHINA_CONTEXT_VARIABLE_GOOGLE_GENAI_API_KEY
    model_name: "gemini-1.5-pro"

invoke_image

Generate images using Gemini.

invoke_video

Generate or analyze video content.

invoke_search

Perform web-grounded search with Gemini.

---

3. Sportradar NFL (sportradar-nfl)

Type: REST API Category: Sports Data Location: machina-templates/connectors/sportradar-nfl/

Description: Sportradar NFL API v7 connector for accessing NFL schedules, game data, injuries, and statistics.

Environment Variables:

• MACHINA_CONTEXT_VARIABLE_SPORTRADAR_NFL_API_KEY - Sportradar API key

Key Features:

• Automatic season type detection (PRE/REG/PST)
• Playoff week conversion (19→1, 20→2)
• Injury synchronization for current + next week
• Extensive unit test coverage

REST Endpoints (via OpenAPI spec):

GET /games/{year}/{season_type}/schedule.json

Get season schedule.

Parameters:

Example Workflow YAML:

- task: rest-api-get
  name: Get NFL schedule
  connector:
    name: sportradar-nfl
    endpoint: /games/{year}/{season_type}/schedule.json
  params:
    api_key: $MACHINA_CONTEXT_VARIABLE_SPORTRADAR_NFL_API_KEY
    year: 2024
    season_type: "REG"

GET /games/{game_id}/summary.json

Get detailed game summary.

GET /teams/{team_id}/injuries.json

Get team injury report.

---

4. WordPress (wordpress)

Type: PyScript Category: Content & Publishing Location: machina-templates/connectors/wordpress/

Description: WordPress REST API connector for creating, updating, and managing posts and content.

Commands:

create_post

Create a new WordPress post.

Input Fields:

Output:

{
  "status": true,
  "data": {
    "id": 123,
    "link": "https://site.com/post-slug"
  }
}

Example Workflow YAML:

- task: publish-content
  name: Create WordPress post
  connector:
    name: wordpress
    command: create_post
  params:
    url: "https://blog.example.com"
    username: $WP_USERNAME
    password: $WP_APP_PASSWORD
    title: "New Article Title"
    content: "<p>Article content here</p>"
    status: "publish"

update_post

Update an existing post.

get_posts

Retrieve posts by criteria.

---

5. API-Football (api-football)

Type: REST API Category: Sports Data Location: machina-templates/connectors/api-football/

Description: Comprehensive soccer data API providing fixtures, standings, statistics, and predictions for 1000+ competitions worldwide.

Environment Variables:

• MACHINA_CONTEXT_VARIABLE_API_FOOTBALL_KEY - API-Football API key

Key Features:

• 1000+ soccer leagues and cups
• Live scores and statistics
• H2H records and predictions
• Player and team statistics

REST Endpoints:

GET /fixtures

Get fixtures by various criteria.

Parameters:

Example Workflow YAML:

- task: rest-api-get
  name: Get fixtures
  connector:
    name: api-football
    endpoint: /fixtures
  headers:
    x-rapidapi-key: $MACHINA_CONTEXT_VARIABLE_API_FOOTBALL_KEY
  params:
    league: 39
    season: 2024
    date: "2024-01-15"

GET /standings

Get league standings.

GET /fixtures/headtohead

Get head-to-head records between teams.

---

6. Sportradar Soccer (sportradar-soccer)

Type: REST API Category: Sports Data Location: machina-templates/connectors/sportradar-soccer/

Description: Sportradar Soccer API for accessing match schedules, lineups, statistics, and live data.

Environment Variables:

• MACHINA_CONTEXT_VARIABLE_SPORTRADAR_SOCCER_API_KEY - Sportradar API key

REST Endpoints:

GET /schedules/{date}/schedule.json

Get matches for a specific date.

GET /sport_events/{event_id}/summary.json

Get detailed match summary with lineups and stats.

Example Workflow YAML:

- task: rest-api-get
  name: Get soccer schedule
  connector:
    name: sportradar-soccer
    endpoint: /schedules/{date}/schedule.json
  params:
    api_key: $MACHINA_CONTEXT_VARIABLE_SPORTRADAR_SOCCER_API_KEY
    date: "2024-01-15"

---

7. Google Storage (google-storage, google-storage-v2)

Type: PyScript Category: Storage & Files Location: machina-templates/connectors/google-storage/

Description: Google Cloud Storage connector for uploading, downloading, and managing files in GCS buckets.

Commands (google-storage):

upload_file

Upload a file to GCS.

Input Fields:

Output:

{
  "status": true,
  "data": {
    "blob_name": "path/to/file.txt",
    "public_url": "https://storage.googleapis.com/..."
  }
}

Example Workflow YAML:

- task: upload-file
  name: Upload to GCS
  connector:
    name: google-storage
    command: upload_file
  params:
    bucket_name: "my-bucket"
    source_file: "/tmp/data.json"
    destination_blob: "data/output.json"
    credentials_json: $GCS_CREDENTIALS

download_file

Download a file from GCS.

---

9. ElevenLabs (elevenlabs)

Type: PyScript Category: Media Generation Location: machina-templates/connectors/elevenlabs/

Description: ElevenLabs text-to-speech connector for generating high-quality voice audio.

Commands:

generate_audio

Generate speech audio from text.

Input Fields:

Output:

{
  "status": true,
  "data": {
    "audio_path": "/tmp/audio.mp3"
  }
}

Example Workflow YAML:

- task: generate-audio
  name: Create podcast audio
  connector:
    name: elevenlabs
    command: generate_audio
  params:
    api_key: $ELEVENLABS_API_KEY
    text: "Welcome to the podcast..."
    voice_id: "21m00Tcm4TlvDq8ikWAM"

---

10. Perplexity (perplexity)

Type: PyScript Category: AI/LLM Services Location: machina-templates/connectors/perplexity/

Description: Perplexity AI connector for web-grounded search and question answering.

Commands:

web_search

Perform web search with AI summarization.

Input Fields:

Example Workflow YAML:

- task: web-search
  name: Research topic
  connector:
    name: perplexity
    command: web_search
  params:
    api_key: $PERPLEXITY_API_KEY
    query: "Latest NFL injury updates"

---

11. Groq (groq)

Type: PyScript Category: AI/LLM Services Location: machina-templates/connectors/groq/

Description: Groq fast inference connector for LLama and Mixtral models with ultra-low latency.

Commands:

invoke_prompt

Generate text with Groq models.

Input Fields:

Example Workflow YAML:

- task: llm-generate
  name: Fast generation with Groq
  connector:
    name: groq
    command: invoke_prompt
  params:
    api_key: $MACHINA_CONTEXT_VARIABLE_GROQ_API_KEY
    model_name: "llama-3.1-70b-versatile"

---

12. FastF1 (fastf1)

Type: PyScript Category: Sports Data Location: machina-templates/connectors/fastf1/

Description: Formula 1 data connector using the FastF1 library for telemetry, lap times, and session data.

Commands:

get_session

Get F1 session data.

Input Fields:

Example Workflow YAML:

- task: get-f1-data
  name: Get qualifying session
  connector:
    name: fastf1
    command: get_session
  params:
    year: 2024
    event: "Monaco"
    session: "Q"

get_telemetry

Get telemetry data for specific laps.

---

13. Stats Perform (stats-perform)

Type: REST API Category: Sports Data Location: machina-templates/connectors/stats-perform/

Description: Stats Perform multi-sport data provider with fixtures, standings, and statistics.

REST Endpoints:

GET /fixtures

Get fixtures for multiple sports.

Example Workflow YAML:

- task: rest-api-get
  name: Get fixtures
  connector:
    name: stats-perform
    endpoint: /fixtures
  params:
    api_key: $STATS_PERFORM_API_KEY
    sport: "soccer"
    date: "2024-01-15"

---

14. Exa Search (exa-search)

Type: PyScript Category: Data & Search Location: machina-templates/connectors/exa-search/

Description: Exa web search connector for AI-powered web research and content discovery.

Commands:

web_search

Search the web with AI ranking.

Input Fields:

Example Workflow YAML:

- task: web-search
  name: Research content
  connector:
    name: exa-search
    command: web_search
  params:
    api_key: $EXA_API_KEY
    query: "NFL playoff predictions 2024"
    num_results: 5

---

15. Stability AI (stability)

Type: PyScript Category: Media Generation Location: machina-templates/connectors/stability/

Description: Stability AI connector for image generation using Stable Diffusion models.

Commands:

generate_image

Generate images from text prompts.

Input Fields:

Example Workflow YAML:

- task: generate-image
  name: Create article image
  connector:
    name: stability
    command: generate_image
  params:
    api_key: $STABILITY_API_KEY
    prompt: "Soccer stadium during sunset"
    width: 1024
    height: 1024

---

Lightweight Connector Documentation

The following connectors are documented with essential information only.

AI/LLM Services

grok

Type: PyScript Purpose: xAI Grok model access Key Command: invoke_prompt

machina-ai

Type: PyScript Purpose: Custom Machina LLM wrapper Key Command: invoke_prompt

machina-ai-fast

Type: PyScript Purpose: Fast inference variant of machina-ai Key Command: invoke_prompt

---

Sports Data APIs

american-football

Type: REST API Purpose: American football data Key Endpoints: /schedule, /roster

mlb-statsapi

Type: PyScript Purpose: MLB statistics via MLB Stats API Key Commands: get_games, get_standings

sportradar-nba

Type: REST API Purpose: NBA data via Sportradar Key Endpoints: /schedule, /standings, /game_summary

sportradar-mlb

Type: REST API Purpose: MLB data via Sportradar Key Endpoints: /schedule, /boxscore

sportradar-nhl

Type: REST API Purpose: NHL data via Sportradar Key Endpoints: /schedule, /standings

sportradar-rugby

Type: REST API Purpose: Rugby data via Sportradar Key Endpoints: /schedule, /match_summary

sportradar-tennis

Type: REST API Purpose: Tennis data via Sportradar Key Endpoints: /schedule, /rankings, /match_summary

---

Content & Publishing

google-speech-to-text

Type: PyScript Purpose: Audio transcription via Google Cloud Key Command: transcribe_audio

docling

Type: PyScript Purpose: Document conversion and processing Key Command: convert_document

---

Storage & Files

storage

Type: PyScript Purpose: Generic storage operations Key Commands: save_file, load_file

temp-downloader

Type: PyScript Purpose: Temporary file download and handling Key Command: download_temp_file

---

Data & Search

oxylabs

Type: PyScript Purpose: Web scraping proxy service Key Command: scrape_website

rss-feed

Type: PyScript Purpose: RSS feed parsing and fetching Key Commands: fetch_feed, parse_feed

---

Betting & Markets

bwin

Type: REST API Purpose: Bwin betting odds and markets Key Endpoints: /odds, /markets

kalshi

Type: REST API Purpose: Kalshi prediction markets Key Endpoints: /markets, /trades

tallysight

Type: PyScript Purpose: Sports betting analytics Key Command: get_analytics

---

Support & Services

zendesk

Type: REST API Purpose: Zendesk support ticket management Key Endpoints: /tickets, /users

---

Usage Patterns

Using Connectors in Workflows

Connectors are invoked in workflow YAML files using the following patterns:

PyScript Connector (with command):

- task: task-name
  name: Descriptive name
  connector:
    name: connector-name
    command: command-name
  params:
    param1: value1
    param2: value2

REST API Connector (with endpoint):

- task: rest-api-get
  name: Descriptive name
  connector:
    name: connector-name
    endpoint: /path/to/endpoint
  headers:
    Authorization: Bearer $API_KEY
  params:
    query_param: value

Environment Variables

Most connectors use environment variables for API keys and credentials. These are referenced with the $MACHINA_CONTEXT_VARIABLE_ prefix:

params:
  api_key: $MACHINA_CONTEXT_VARIABLE_OPENAI_API_KEY

Common environment variable patterns:

• $MACHINA_CONTEXT_VARIABLE_OPENAI_API_KEY
• $MACHINA_CONTEXT_VARIABLE_GOOGLE_GENAI_API_KEY
• $MACHINA_CONTEXT_VARIABLE_SPORTRADAR_NFL_API_KEY
• $MACHINA_CONTEXT_VARIABLE_API_FOOTBALL_KEY

Error Handling

Connectors return standardized response formats:

Success Response:

{
  "status": true,
  "data": { ... },
  "message": "Success message"
}

Error Response:

{
  "status": false,
  "message": "Error description"
}

Data Abstraction in Workflow Outputs

Important: The SDK automatically unwraps the data object when passing values to workflow outputs.

In the connector (Python):

def invoke_upload(request_data):
    # ... processing ...
    return {
        "status": True,
        "data": {                         # Results go inside "data"
            "video_path": "/tmp/video.mp4",
            "filename": "output.mp4",
            "duration": 30
        },
        "message": "Upload successful"
    }

In the workflow (YAML):

- type: connector
  name: upload-video
  connector:
    name: google-storage
    command: invoke_upload
  inputs:
    file_path: "$.get('source_path')"
  outputs:
    video_path: "$.get('video_path')"    # Access directly, NOT $.get('data').get('video_path')
    filename: "$.get('filename')"
    duration: "$.get('duration')"

How it works:

Connector returns:              Workflow context receives:
─────────────────────           ──────────────────────────
{
  "status": True,         →     status = True
  "data": {               →     video_path = "/tmp/video.mp4"
    "video_path": "...",  →     filename = "output.mp4"
    "filename": "...",    →     duration = 30
    "duration": 30        →     message = "Upload successful"
  },
  "message": "..."
}

Key points:

• Use $.get('field') to access fields from data
• status and message are also available directly
• Do NOT use $.get('data').get('field') - the unwrapping is automatic

---

Connector Development

• Location: machina-templates/connectors/
• Template Structure:

  connector-name/
  ├── connector-name.yml      # Connector metadata
  ├── connector-name.py       # PyScript implementation
  ├── connector-name.json     # OpenAPI spec (REST)
  ├── _install.yml           # Installation metadata
  └── test-credentials.yml   # Credential tests

Testing Connectors

Connectors can be tested using the credential test files:

# test-credentials.yml example
test:
  connector: connector-name
  command: test-command
  params:
    api_key: $TEST_API_KEY

Create

Scaffold individual Machina YAML components with correct structure.

Trigger

• "Create new template", "Scaffold agent template"

Process

1. Gather Requirements

Ask user for:

• Template name: kebab-case (e.g., sports-predictions)
• Template type: agent-template or connector
• Target repo: the repository where this template will live
• Components needed: agents, workflows, prompts, mappings, connectors

2. Create Directory Structure

# Agent template
mkdir -p agent-templates/{name}/{agents,workflows,prompts,mappings,scripts,documents}

# Connector
mkdir -p connectors/{name}

3. Generate Files

Read the relevant schema before generating each component:

Install order in `_install.yml`: connectors → documents → prompts → mappings → workflows → agents → skills.

4. Cross-Entity Wiring

After generating individual files, verify these connections:

• Agent → Workflows: Each workflows[].name in the agent must match a workflow.name in a workflow file.
• Workflow → Prompts: Each prompt task name must match a prompts[].name in a prompt file.
• Workflow → Connectors: context-variables must declare credentials for every connector used in tasks.
• Workflow → Mappings: Each mapping task name must match a mappings[].name in a mapping file.
• `_install.yml` → Files: Every datasets[].path must point to an existing file.

Template Type Patterns

Chat Agent (Conversation)

• Thread management via context-agent.thread_id and context-agent.messages
• Typical flow: reasoning → main → response workflows

One-Shot Agent (No Thread)

• Auto-creates thread if needed, no conversation state

Periodic Agent (Scheduled)

• config-frequency in context for scheduling
• Idempotency checks, batch processing
• Reference: machina-templates/agent-templates/power-ranking-periodic

Connector Only

• PyScript or REST API, reusable across templates
• Reference: machina-templates/connectors/google-genai

Differences from init

Related

• Init — Full project scaffold with boilerplate
• Validate — Validate YAML before installing
• Install — Deploy templates
• Schemas: agent · workflow · prompt · connector · mapping · setup · skill

Trigger

Use this reference when the user mentions: "frontend integration", "Next.js API", "document search API", "frontend API", "Next.js integration", "API routes".

---

Frontend API Integration Guide

Quick reference for integrating Next.js frontends with Machina Client API.

API Route Pattern

Create API routes in app/api/ that proxy to Machina Client API:

// app/api/documents/route.ts
import { NextRequest, NextResponse } from "next/server"

export async function GET(req: NextRequest) {
  const api_url = process.env.MACHINA_CLIENT_URL
  const bearer = process.env.MACHINA_API_KEY

  const headers = {
    "X-Api-Token": `${bearer}`,
    "Content-Type": "application/json",
  }

  const response = await fetch(`${api_url}/document/search`, {
    method: "POST",
    headers,
    body: JSON.stringify({ filters: { name: "my-document" } })
  })

  const payload = await response.json()
  return NextResponse.json({ status: true, data: payload.data })
}

Document Search

Basic Search

const body = {
  filters: { name: "ros-output" },  // Required: document name
  page: 1,
  page_size: 50
}

Sorters

Format: ["field", direction] where direction is 1 (asc) or -1 (desc)

// Correct
sorters: ["created", -1]  // Most recent first

// Wrong - causes 500 error
sorters: [["created", -1]]

Multiple Filters with $and

Combine multiple conditions:

const filters: any = { name: "ros-output" }
const andConditions: any[] = []

if (competition) {
  andConditions.push({
    "$or": [
      { "metadata.competition": { $regex: competition, $options: 'i' } },
      { "value.match.competition": { $regex: competition, $options: 'i' } }
    ]
  })
}

if (startDate) {
  andConditions.push({ created: { $gte: startDate } })
}

if (andConditions.length > 0) {
  filters["$and"] = andConditions
}

Text Search

Search across multiple fields:

if (search) {
  andConditions.push({
    "$or": [
      { "metadata.match_title": { $regex: search, $options: 'i' } },
      { "metadata.event_code": { $regex: search, $options: 'i' } },
      { "value.title": { $regex: search, $options: 'i' } }
    ]
  })
}

Document Structure

Documents have standard fields:

interface Document {
  _id: string           // MongoDB ObjectId
  name: string          // Document type identifier
  created: string       // ISO date (use for sorting)
  updated: string       // ISO date
  metadata: {           // Indexed, searchable fields
    event_code?: string
    competition?: string
    // ... custom fields
  }
  value: {              // Main document content
    title?: string
    spreadsheet_url?: string  // GCS file URLs
    csv_url?: string
    // ... custom data
  }
}

Key points:

• Use metadata for fields you need to filter/search
• Use value for the main document payload
• created/updated are auto-managed by the API
• Files (xlsx, csv) are stored in GCS, URLs in value

File Downloads

Fetch files from GCS URLs stored in documents:

// Get document
const doc = await fetchDocument(id)
const fileUrl = doc.value?.spreadsheet_url

if (!fileUrl) {
  return NextResponse.json({ error: "File not available" }, { status: 404 })
}

// Proxy the file
const fileResponse = await fetch(fileUrl)
const buffer = await fileResponse.arrayBuffer()

return new NextResponse(buffer, {
  headers: {
    'Content-Type': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
    'Content-Disposition': `attachment; filename="${filename}"`,
  }
})

Common Patterns

Debounced Search Input

const [localSearch, setLocalSearch] = useState(filters.search)

useEffect(() => {
  const timer = setTimeout(() => {
    if (localSearch !== filters.search) {
      onFilterChange({ ...filters, search: localSearch })
    }
  }, 300)
  return () => clearTimeout(timer)
}, [localSearch])

Loading States

const fetchData = useCallback(async () => {
  setLoading(true)
  try {
    const response = await fetch(`/api/endpoint?${params}`)
    const result = await response.json()
    if (result.status && result.data) {
      setData(result.data)
    }
  } finally {
    setLoading(false)
  }
}, [dependencies])  // Include all filter/sort dependencies

Availability Checks

Check if optional resources exist before showing actions:

const hasXlsx = !!output.value?.spreadsheet_url
const hasCsv = !!output.value?.csv_url

<Button disabled={!hasXlsx}>
  Download Excel {!hasXlsx && '(unavailable)'}
</Button>

Environment Variables

MACHINA_CLIENT_URL=http://localhost:31000
MACHINA_API_KEY=your-api-key

Quick Reference

Init

Scaffold a new Machina template project from scratch with directory structure, configuration files, and documentation.

Trigger

• "Init template", "Initialize new template", "Scaffold new template project"

Process

1. Gather Requirements

2. Validate Inputs

1. Template name: lowercase, hyphens only (^[a-z0-9-]+$) 2. Target repo exists: path must be valid 3. Template does not already exist: no overwriting 4. Template type directory exists: create if needed

3. Create Directory Structure

# Agent template
mkdir -p {repo}/agent-templates/{name}/{agents,workflows,prompts,mappings,scripts,setup}

# Connector
mkdir -p {repo}/connectors/{name}

4. Generate _install.yml

Schema reference: setup.md Part 1

setup:
  title: "{title}"
  description: "{description}"
  category:
    - {category}
  estimatedTime: 10 minutes
  features:
    - {description}
  integrations:
    - {integrations}
  status: available
  value: {template_type}/{template_name}
  version: {version}

datasets:
  - type: "documents"
    path: "setup/_index.yml"
  - type: "prompts"
    path: "prompts/main-prompts.yml"
  - type: "workflow"
    path: "workflows/main-workflow.yml"
  - type: "workflow"
    path: "_folders.yml"
  - type: "agent"
    path: "_setup.yml"
  - type: "agent"
    path: "agents/main-executor.yml"

5. Generate setup/_index.yml

Schema reference: setup.md Part 2

documents:
  - name: "{template_name}-config"
    title: "{title} Config"
    filename: "config.json"
    filetype: json
    metadata:
      category: config
      template: "{template_name}"

And the corresponding setup/config.json:

{
  "title": "{title} Configuration",
  "enabled": true
}

6. Generate _folders.yml

Folder/document setup workflow (boilerplate — not in schemas):

workflow:
  name: "{template_name}-folders"
  title: "{title} | Setup Folders"
  description: "Setup Folders"
  inputs:
    force-setup: "$.get('force-setup') == 'true'"
  outputs:
    setup-register: "$.get('setup-register')"
    workflow-status: "($.get('setup-register') is True or $.get('force-setup') is True) and 'skipped' or 'executed'"
  tasks:

    - type: "document"
      name: "load-setup-register"
      description: "Search for setup-register"
      config:
        action: "search"
        search-limit: 1
        search-vector: false
      inputs:
        name: "'setup-register'"
      outputs:
        setup-register: "$.get('documents')[0].get('value').get('setup', False) if $.get('documents') else False"

    - type: "document"
      name: "{template_name}-install-documents"
      description: "Install documents."
      condition: "$.get('setup-register') is not True or $.get('force-setup') is True"
      config:
        action: "update"
        embed-vector: false
        force-update: true
      documents:
        setup-playground: |
          [
            {
              "title": "{title}",
              "name": "{template_name}-main",
            }
          ]
        setup-register: |
          {
            "setup": True
          }
        site-structure: |
          [
          ]
        doc-structure: |
          [
            {
              "title": "Catalogue",
              "isActive": True,
              "icon": "folder",
              "items": [
                {
                  "name": "documents",
                  "title": "Documents",
                  "description": "Configuration documents.",
                  "category": "Catalogue",
                  "metadata": {
                    "name": ["{template_name}-document"]
                  },
                  "sorters": ['_id', -1],
                  "view": "list"
                }
              ]
            }
          ]

7. Generate _setup.yml

Setup agent that runs the folders workflow (boilerplate):

agent:
  name: "setup-{template_name}"
  title: "Setup {title}"
  description: "Setup {title}"
  context:
    config-frequency: 99999999
  workflows:
    - name: "{template_name}-folders"
      description: "Setup Folders"
      condition: "$.get('setup-register') is not True"
      outputs:
        setup-register-status: "$.get('workflow-status', False)"

8. Generate Stub Files

Schema references: agent.md · prompt.md · workflow.md

agents/main-executor.yml

agent:
  name: "{template_name}-executor"
  title: "{title} - Executor"
  description: "{description}"
  context:
    status: "inactive"
  context-agent:
    messages: "$.get('messages', [])"
    thread_id: "$.get('thread_id', None)"
  workflows:
    - name: "{template_name}-main-workflow"
      description: "Main workflow"
      inputs:
        input_message: "$.get('messages', [])"
        thread_id: "$.get('thread_id')"
      outputs:
        response: "$.get('response')"

prompts/main-prompts.yml

prompts:
  - type: "prompt"
    name: "{template_name}-analyzer"
    title: "{title} - Analyzer"
    description: "Analyzes input and generates response."
    instruction: |
      You are {title}. {description}

      You receive the following inputs:
      - _0-input-data: The user input data

      Your task is to:
      1. Analyze the input data
      2. Generate an appropriate response
    schema:
      title: "{template_name}Analyzer"
      description: "Analysis result"
      type: object
      required: [response]
      properties:
        response:
          type: string
          description: "The generated response"

workflows/main-workflow.yml

workflow:
  name: "{template_name}-main-workflow"
  title: "{title} - Main Workflow"
  description: "Main workflow for {template_name}"
  context-variables:
    debugger:
      enabled: true
    machina-ai:
      credential: "$TEMP_CONTEXT_VARIABLE_MACHINA_AI_API_KEY"
  inputs:
    input_message: "$.get('input_message', [])"
    thread_id: "$.get('thread_id')"
  outputs:
    response: "$.get('response', '')"
    workflow-status: "$.get('response') is not None and 'executed' or 'skipped'"
  tasks:
    - type: "prompt"
      name: "{template_name}-process"
      description: "Process input with LLM"
      connector:
        name: "machina-ai"
        command: "invoke_prompt"
        model: "machina-ai"
      inputs:
        _0-input-data: "$.get('input_message')"
      outputs:
        response: "$"

9. Generate Documentation

Create README.md and CHANGES.md with template metadata.

10. Display Summary

Template initialized!

{repo}/agent-templates/{name}/
├── _install.yml           # Installation manifest
├── _folders.yml           # Folder/document setup
├── _setup.yml             # Setup agent
├── README.md
├── CHANGES.md
├── agents/main-executor.yml
├── prompts/main-prompts.yml
├── workflows/main-workflow.yml
├── setup/
│   ├── _index.yml
│   └── config.json
├── scripts/               # (empty)
└── mappings/              # (empty)

Next steps:
1. Edit prompts and workflows for your use case
2. Ask to "validate template" to verify syntax
3. Ask to "install template" to deploy

Differences from create

Related

• Create — Scaffold individual YAML components
• Validate — Validate before installing
• Install — Deploy templates
• Analyze — Inspect template structure

Install

Install Machina templates from local filesystem or Git repositories.

Trigger

• "Install template", "Import template from git"

Process

1. Identify Template Source

Ask user for:

• Local path: {repo}/agent-templates/{template-name}
• Git URL: repository URL + branch + template path

2. Read Installation Manifest

Read _install.yml to understand template metadata, required datasets, and dependencies. See setup.md for the complete _install.yml schema.

Key things to check:

• Template title, description, version
• Required integrations (connectors)
• Dataset list and installation order

3. Check Prerequisites

Before installing, verify: 1. Required connectors exist in target environment 2. Secrets are configured for integrations

# Check if connector exists
mcp__docker_localhost__connector_search({
    "filters": {"name": "google-genai"},
    "page": 1,
    "page_size": 1
})

# Check secrets
mcp__docker_localhost__check_secrets({
    "name": "GOOGLE_GENAI_API_KEY"
})

4. Install Template

From Local Filesystem

{mcp}import_template_from_local(
    template="agent-templates/{template-name}",
    project_path="/app/{repo-name}/agent-templates/{template-name}"
)

Note: project_path must be the path inside the Docker container (usually /app/{repo-name}/...).

From Git Repository

{mcp}import_template_from_git(repositories=[{
    "repo_url": "https://github.com/org/repo",
    "template": "agent-templates/{template-name}",
    "branch": "main"
}])

5. Verify Installation

After importing, verify components were created:

# Check agent exists
{mcp}search_agents(
    filters={"name": "my-agent"},
    sorters=["created", -1],
    page=1,
    page_size=1
)

# Check workflows exist
{mcp}search_workflows(
    filters={"name": "my-workflow"},
    sorters=["created", -1],
    page=1,
    page_size=1
)

See api.md for the full MCP operations reference.

MCP Server Selection

Additional environments depend on the project's MCP configuration. Pattern: mcp__{project}-{env}__.

Common Issues

"Connector not found"

Install the connector first:

mcp__docker_localhost__get_local_template({
    "template": "connectors/google-genai",
    "project_path": "/app/machina-templates/connectors/google-genai"
})

"Secret not configured"

Create the secret — see Secrets for the full process:

mcp__docker_localhost__create_secrets({
    "data": {
        "name": "GOOGLE_GENAI_API_KEY",
        "key": "your-api-key-here"
    }
})

Import succeeds but agent not found

The template path might be wrong. Verify the local path exists before importing.

Related

• Validate — Validate YAML before installing
• Secrets — Configure credentials
• Analyze — Verify installation

Secrets

Configure secrets in the Machina vault for use with connectors in workflows.

Trigger

• "Configure secrets for a connector", "Add API key to vault"

Key Concepts

Naming Convention

Secrets MUST follow the TEMP_CONTEXT_VARIABLE_* pattern:

TEMP_CONTEXT_VARIABLE_{SERVICE}_{FIELD}

Examples:

• TEMP_CONTEXT_VARIABLE_GOOGLE_STORAGE_API_KEY
• TEMP_CONTEXT_VARIABLE_OPENAI_API_KEY
• TEMP_CONTEXT_VARIABLE_SPORTRADAR_API_KEY

How Secrets Flow

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Vault Secret  │ --> │ context-variables│ --> │ Connector inputs│
│                 │     │   in workflow    │     │                 │
│ name: TEMP_...  │     │ $TEMP_...        │     │ $.get('field')  │
│ key: "value"    │     │                  │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Step-by-Step Process

1. Create Secrets in Vault

Create ONE secret at a time:

mcp__docker-localhost__create_secrets({
  "name": "TEMP_CONTEXT_VARIABLE_GOOGLE_STORAGE_BUCKET_NAME",
  "key": "machina-templates-bucket-default"
})

mcp__docker-localhost__create_secrets({
  "name": "TEMP_CONTEXT_VARIABLE_GOOGLE_STORAGE_API_KEY",
  "key": '{"type":"service_account","project_id":"...",...}'
})

2. Verify Secrets Exist

mcp__docker-localhost__check_secrets(name="TEMP_CONTEXT_VARIABLE_GOOGLE_STORAGE_API_KEY")
# Returns: {"status": "success", "message": "Secret ... exists."}

3. Configure Workflow

Add context-variables section to workflow YAML (see workflow.md for full context-variables reference):

workflow:
  name: my-workflow
  context-variables:
    google-storage:
      api_key: $TEMP_CONTEXT_VARIABLE_GOOGLE_STORAGE_API_KEY
      bucket_name: $TEMP_CONTEXT_VARIABLE_GOOGLE_STORAGE_BUCKET_NAME

The $ prefix tells the SDK to look up the secret by name from vault.

4. Pass Credentials to Connector

In connector tasks, pass credentials via inputs:

- type: connector
  name: upload-to-gcs
  connector:
    name: google-storage
    command: invoke_upload
  inputs:
    api_key: "$.get('api_key')"
    bucket_name: "$.get('bucket_name')"

Common Mistakes

Reference: Known Credential Patterns

context-variables:
  google-genai:
    credential: $TEMP_CONTEXT_VARIABLE_VERTEX_AI_CREDENTIAL
    project_id: $TEMP_CONTEXT_VARIABLE_VERTEX_AI_PROJECT_ID
    api_key: $TEMP_CONTEXT_VARIABLE_GOOGLE_GENERATIVE_AI_API_KEY
  google-storage:
    api_key: $TEMP_CONTEXT_VARIABLE_GOOGLE_STORAGE_API_KEY
    bucket_name: $TEMP_CONTEXT_VARIABLE_GOOGLE_STORAGE_BUCKET_NAME
  machina-ai:
    api_key: $TEMP_CONTEXT_VARIABLE_SDK_OPENAI_API_KEY

MCP Commands

# Create
mcp__docker-localhost__create_secrets({"name": "TEMP_...", "key": "value"})

# Check
mcp__docker-localhost__check_secrets(name="TEMP_...")

# Delete
mcp__docker-localhost__delete_secrets(name="TEMP_...")

Troubleshooting

"API key is required" Error

1. Check secret exists: check_secrets(name="TEMP_...") 2. Verify workflow has context-variables section 3. Ensure connector inputs pass $.get('api_key') 4. Confirm secret name follows TEMP_CONTEXT_VARIABLE_* pattern

Secret Creation Fails with 500 Error

• Create secrets one at a time
• For JSON values, ensure proper escaping
• Check value length and character validity

Related

• Install — Install templates (requires secrets)
• Analyze — Discover required credentials

Trace

Trace the execution chain of any Machina entity — from skill down to individual task inputs/outputs. Visualizes data flow and variable propagation for debugging.

Difference from other references:

• analyze — static overview of all template components
• validate — checks YAML errors
• `trace` — traces one specific entity, showing execution chain with variable propagation

Trigger

• "Trace agent", "Trace workflow", "Trace skill", "Show variable flow", "Show input/output chain"

Entry Points

Trace can start from any level. Each level expands downward:

Skill → Agent → Workflow → Task → Input/Output

---

Skill Trace

Process

1. Read skill.yml and extract fields per skill.md: name, description, references, entry points (workflows and/or agents) 2. For each workflow entry point: trace as Workflow Trace (below) 3. For each agent entry point: trace as Agent Trace (below) 4. List all references with their reference_id

Output

SKILL: {skill-name}
  version: {version} | status: {status}
  category: {categories}
  domain: {domain}

  references:
    - {reference_id}: {title}
    - {reference_id}: {title}

  entry points:

    [workflow] {workflow-name}
      inputs:  {comma-separated input names with defaults}
      outputs: {comma-separated output names}

    [agent] {agent-name}
      inputs:  {comma-separated input names with defaults}
      outputs: {comma-separated output names}

Then expand each entry point using the Agent Trace or Workflow Trace format below.

---

Agent Trace

Process

1. Identify agent: Receive agent YAML path or template path + agent name

• Direct path: {repo}/agent-templates/{template-name}/agents/{agent}.yml
• Discover: Look in agents/*.yml or _install.yml for type: agent entries

2. Parse agent YAML per agent.md: name, title, status, frequency, context-agent, context-variables, workflows list 3. For each workflow: name, description, condition, inputs, outputs 4. Expand each workflow using the Workflow Trace format below

Output

AGENT: {agent-name}
  frequency: {N} min | status: {status}
  context-agent:
    {param}: {expression}

  context-variables:
    {connector-name}:
      {key}: {value-or-secret-ref}

  ┌─ STEP 1: {workflow-name}
  │  condition: {condition or "(none)"}
  │  inputs:  {comma-separated input variable names}
  │  outputs: {comma-separated output variable names}
  │
  │  tasks:
  │    1. [{task-type-badge}]  {task-name}
  │       inputs:  {key}: {expression}
  │       outputs: {key}: {expression}
  │       condition: {condition if present}
  │       {connector details if type=connector}
  │    2. [{task-type-badge}]  {task-name}
  │       inputs:  {key}: {expression}
  │       outputs: {key}: {expression}
  │
  ├─ STEP 2: {workflow-name}
  │  ...
  │
  └─ STEP N: {last-workflow-name}
     ...

---

Workflow Trace

Process

1. Identify workflow: Receive workflow YAML path or name 2. Parse workflow YAML per workflow.md: name, inputs, outputs, context-variables, tasks 3. Parse each task based on type:

• All types: type, name, description, condition, foreach, inputs, outputs
• document: config.action, filters, document_name, documents, metadata — per document.md
• connector: connector.name, connector.command
• prompt: connector config (name, command, model)
• mapping: input/output transformation

Output

WORKFLOW: {workflow-name}
  context-variables:
    {connector-name}:
      {key}: {value-or-secret-ref}

  inputs:
    {key}: {expression}
  outputs:
    {key}: {expression}

  tasks:
    1. [{task-type-badge}]  {task-name}
       condition: {condition if present}
       foreach: {items-expression} {concurrent?}
       inputs:
         {key}: {expression}
       outputs:
         {key}: {expression}

    2. [{task-type-badge}]  {task-name}
       connector: {name} > {command}
       inputs:
         {key}: {expression}
       outputs:
         {key}: {expression}

    3. [{task-type-badge}]  {task-name}
       document_name: {collection}
       filters:
         {key}: {expression}
       outputs:
         {key}: {expression}

---

Document Trace

Reverse trace: find all workflows that interact with a specific document.

Process

1. Identify document: Receive document name (e.g., sport:Event, thread) 2. Scan all workflow YAMLs in the template for type: document tasks 3. Match tasks where document_name, filters.name, or filters.document_id references the target document 4. Categorize each match by operation

Output

DOCUMENT: {document-name}

  READERS (search):
    - {workflow-name} > task {N}: {task-name}
      filters: {filter-expression}
      outputs: {extracted-fields}

  WRITERS (save/bulk-save):
    - {workflow-name} > task {N}: {task-name}
      documents: {data-expression}
      metadata: {metadata-fields}
      embed-vector: {true/false}

  UPDATERS (update/bulk-update):
    - {workflow-name} > task {N}: {task-name}
      filters: {match-expression}
      documents: {update-expression}

  DELETERS (delete):
    - {workflow-name} > task {N}: {task-name}
      filters: {match-expression}

---

Input/Output Trace

Trace the lifecycle of a specific variable across the entire execution chain.

Process

1. Identify variable: Receive variable name (e.g., fixtures, thread_id, api_key) 2. Scan all YAMLs (agent context-agent, workflow inputs/outputs, task inputs/outputs, conditions) 3. Build chain: origin → transformations → consumers

Output

VARIABLE: {variable-name}

  ORIGIN:
    {entity-type}: {entity-name}
      {field}: {expression}

  CHAIN:
    1. {workflow-name} > {task-name} (outputs)
       {variable}: {expression}
    2. {workflow-name} > {task-name} (inputs)
       {variable}: {expression}
    3. {workflow-name} (condition)
       {condition-expression}

  DEAD: {true/false}
    (true if no downstream consumer reads this variable)

---

Summaries

After any trace, append these summary sections when relevant:

Connectors Used

CONNECTORS USED:
  {connector-name} ({N} commands)
    - {command_name}  ← step {N}, task {N}

Documents Touched

DOCUMENTS TOUCHED:
  read:   {doc-name}, {doc-name}
  write:  {doc-name}
  update: {doc-name}
  delete: {doc-name}

Variable Chain

VARIABLE CHAIN:
  {var} → {origin} → {consumers}
  {var} ← {origin} → {consumers, conditions}

Dead Variables

Variables set in outputs but never consumed downstream.

DEAD VARIABLES:
  {var} ← {workflow-name} (outputs, never read)

---

Task Type Badges

Foreach annotation: Append (foreach, concurrent) or (foreach) to the badge line.

Connector detail line: connector: {name} > {command}

---

Execution Mode

When the user asks to trace a real execution (mentions times, durations, status, failures), switch to execution mode. See api.md for MCP operation details.

Trigger

• "Trace last execution of [agent]"
• "What failed in the last run of [agent]?"
• "Show execution times for [workflow]"

E1. Select MCP Server

Additional environments depend on the project's MCP configuration. Pattern: mcp__{project}-{env}__.

E2. Find Executions

# Agent executions
{mcp}search_agent_executions(
    filters={"name": "{agent-name}"},
    sorters=["date", -1],
    page=1,
    page_size=5
)

# Workflow executions
{mcp}search_workflow_executions(
    filters={"name": "{workflow-name}"},
    sorters=["date", -1],
    page=1,
    page_size=5
)

Present recent executions with status, duration, tokens.

E3. Get Full Execution

# Agent execution (includes workflow list)
{mcp}get_agent_execution(
    agent_id="{execution_id}",
    compact=False
)

# Workflow execution (includes task list)
{mcp}get_workflow_execution(
    workflow_id="{workflow_run_id}",
    compact=False
)

E4. Output Execution Trace

AGENT: {agent-name}  [RUN: {execution_id}]
  status: {status} | duration: {total_time}s | tokens: {total_tokens}
  started:  {date}
  finished: {finished_time}
  workflows: {completed}/{total}

  ┌─ STEP 1: {workflow-name}  [OK 3.2s]
  │  tasks:
  │    1. [doc:search]  load-config                      OK   0.4s
  │       inputs:  name: "config"
  │       outputs: competitions (3 items)
  │    2. [connector]   fetch-data                        OK   3.8s  ← slowest
  │       connector: my-connector > get_schedules
  │       inputs:  league_id: "sr:league:1"
  │       outputs: schedules (180 items)
  │
  ├─ STEP 2: {workflow-name}  [SKIP]
  │  reason: condition not met (has_live=False)
  │
  └─ STEP 3: {workflow-name}  [OK 0.9s]
     tasks:
       1. [doc:update]  unlock-season                    OK   0.9s
          inputs:  status: "unlocked"

EXECUTION SUMMARY:
  total:     4.1s
  tokens:    1,240
  workflows: 2/3 executed, 1 skipped
  slowest:   fetch-data (3.8s, step 1)

Key annotations: 1. Timing per task: OK 0.4s after each task name 2. Slowest task: ← slowest annotation 3. Skip reason: condition that evaluated false with actual values 4. Error details: FAIL with inline error message 5. Actual values: Real input/output values from execution 6. Foreach count: (foreach, 2 items) 7. Execution summary: Totals, bottleneck, skip/fail counts

E5. Failure Analysis

If any task has status error:

FAILURES:
  step 3, task 3: fetch-schedules
    status:  error
    time:    3.8s
    error:   "HTTPError 429: Rate limit exceeded"
    inputs:  league_id: "sr:league:1", season: "2025"
    impact:  blocks tasks 4-7 (parsed_fixtures never set)
    suggestion: Check API rate limits / add retry logic

E6. Performance Insights (optional)

If user asks for performance analysis, fetch multiple executions and analyze patterns:

PERFORMANCE:
  avg execution:  18.2s (last 10 runs)
  p95 execution:  32.1s
  most common skip: steps 4-5 (72% of runs)
  most common fail: fetch-* (3%, rate limits)

TIMING BREAKDOWN:
  external API calls:  8.2s (58%)
  document operations:  4.8s (34%)
  connector (internal): 2.0s (14%)

---

Mode Summary

Tips

• Use static mode to understand design and variable flow before deploying
• Use execution mode to debug failures and find bottlenecks
• Start from skill to see all entry points, narrow to agent or workflow
• Use document trace to find all workflows that interact with a specific collection
• Use input/output trace to follow a variable across the entire chain
• Look for dead variables — outputs no downstream workflow consumes
• Check conditions — a workflow that never executes means empty outputs

Related

• Analyze — Full template component overview
• Validate — YAML structure validation
• API — MCP operations for execution queries

Validate

Validate template YAML files against correct patterns before installation.

Trigger

• "Validate template", "Check template YAML"

Process

1. Identify Template Path

Get the template directory path from the user.

2. Check Directory Structure

template-name/
├── _install.yml          # Required
├── agents/               # Agent definitions
├── workflows/            # Workflow definitions
├── prompts/              # Prompt definitions
└── ...

3. Validate Each Component

For each file type, read the corresponding schema and check:

4. Validate Expressions

5. Validate Cross-References

• Every workflows[].name in agent files → matches a workflow name
• Every prompt task name in workflows → matches a prompt name
• Every mapping task name in workflows → matches a mapping name
• Every datasets[].path in _install.yml → file exists
• Every connector in context-variables → has credentials configured

6. Report Results

Template Validation Report: template-name
==========================================

_install.yml: ✅ Valid
  - setup.title: "Template Name"
  - datasets: 15 items

agents/executor.yml: ✅ Valid
  - name: template-name-executor
  - workflows: 12 defined

workflows/main.yml: ❌ ERRORS
  Line 8: Wrong inputs format - use $.get('param')
  Line 15: Unknown task type 'llm' - use 'prompt'

OVERALL: ❌ 2 errors found. Fix before installing.

Validation Checklist

Related

• Create — Scaffold YAML components
• Install — Deploy validated templates
• Schemas: agent · workflow · prompt · connector · mapping · setup · skill

Agent YAML Schema

Complete reference for agent YAML files. Agents orchestrate workflows and define execution context.

Location: agent-templates/<template-name>/agents/<agent-name>.yml

---

Root Structure

agent:
  name: <string>           # Required. Unique identifier (kebab-case)
  title: <string>           # Required. Human-readable title
  description: <string>     # Required. What this agent does
  context: <object>         # Optional. Static agent configuration
  context-agent: <object>   # Optional. Dynamic input parameters from execution payload
  context-variables: <obj>  # Optional. Connector credentials and settings
  documents: <list>         # Optional. Embedded document definitions
  jobs: <list>              # Optional. Scheduled jobs (Celery Beat)
  workflows: <list>         # Required. Ordered list of workflows to execute

---

Field Reference

name (required)

Unique identifier for the agent. Must be kebab-case. Used to reference the agent in _install.yml and API calls.

name: machina-assistant-executor

title (required)

Human-readable display name.

title: Machina Assistant - Chat Executor

description (required)

Description of the agent's purpose. Can be a single line or multiline.

# Single line
description: AI-powered assistant for platform questions

# Multiline
description: |
  An intelligent agent that generates engaging social media content
  for soccer teams using real-time statistics and news insights

context (optional)

Static configuration values. Set once, available throughout execution.

context:
  status: "inactive"              # Agent activation status
  config-frequency: 10            # Periodic execution interval (minutes)

Known `context` fields:

Usage patterns:

# Chat agent (on-demand, starts inactive)
context:
  status: "inactive"

# Periodic agent (scheduled, no status needed)
context:
  config-frequency: 10

# Periodic agent that starts inactive
context:
  config-frequency: 10
  status: "inactive"

# One-time setup agent (run once, very high frequency = practically disabled)
context:
  config-frequency: 99999999

context-agent (optional)

Dynamic input parameters extracted from the execution payload ($.get()). These are the parameters the caller passes when triggering the agent.

# Chat agent — receives thread and messages
context-agent:
  thread_id: $.get('thread_id', None)
  messages: $.get('messages', [])

# One-shot agent — receives specific parameters
context-agent:
  team_a: $.get('team_a')
  team_b: $.get('team_b')
  language: $.get('language', 'en')

# Event-driven agent — receives event code
context-agent:
  event_code: "$.get('event_code')"

# Multi-parameter agent — receives user profile
context-agent:
  name: $.get('name')
  email_address: $.get('email_address')
  favorite_team: $.get('favorite_team')
  language: $.get('language')

context-variables (optional)

Connector credentials and configuration. Usually defined at the workflow level, but can also appear at the agent level.

context-variables:
  debugger:
    enabled: true
  google-genai:
    credential: $TEMP_CONTEXT_VARIABLE_VERTEX_AI_CREDENTIAL
    project_id: $TEMP_CONTEXT_VARIABLE_VERTEX_AI_PROJECT_ID

jobs (optional)

Declarative scheduled jobs evaluated by Celery Beat. Each job dispatches a skill or agent at a defined interval or cron schedule.

jobs:
  - name: <string>           # Required. Unique job identifier
    enabled: <boolean>       # Required. Toggle on/off
    type: <string>           # Required. "skill" or "agent"
    target: <string>         # Required. Skill or agent name to dispatch
    interval: <integer>      # Seconds between runs (mutually exclusive with cron)
    cron: <string>           # Cron expression (mutually exclusive with interval)
    context: <object>        # Optional. Passed as context-agent to target

Fields:

Scheduling: Celery Beat ticks every 5 seconds. On each tick, agents with status: "active" and jobs.enabled: True are evaluated. Jobs fire when the interval/cron is due based on last_execution.

Auto-managed fields (set by scheduler at runtime, not in YAML):

• last_execution — timestamp of last dispatch
• last_status — "dispatched" after successful dispatch

Examples:

# Interval-based: run every 30 seconds
jobs:
  - name: "quick-sync"
    enabled: true
    type: "skill"
    target: "my-sync-skill"
    interval: 30

# Cron-based: every Tuesday at 11:00
jobs:
  - name: "weekly-report"
    enabled: true
    type: "agent"
    target: "my-report-agent"
    cron: "0 11 * * 2"
    context:
      report_type: "weekly"
      language: "en"

# Multiple jobs on one agent
jobs:
  - name: "frequent-check"
    enabled: true
    type: "skill"
    target: "health-check-skill"
    interval: 10
  - name: "daily-cleanup"
    enabled: false
    type: "agent"
    target: "cleanup-agent"
    cron: "0 3 * * *"

Cron expression reference (5-field):

workflows (required)

Ordered list of workflows to execute. Workflows run sequentially — each workflow can access outputs from previous workflows via $.get().

workflows:
  - name: <string>            # Required. Workflow name (must match a workflow YAML)
    description: <string>     # Required. What this workflow step does
    condition: <expression>   # Optional. Python expression — skip if False
    inputs: <object>          # Optional. Values passed to the workflow
    outputs: <object>         # Optional. Values extracted from workflow response
    foreach: <object>         # Optional. Loop execution over a list

---

Workflow Entry Reference

name (required)

Must match the name field of an installed workflow YAML.

- name: machina-assistant-reasoning

Note: The same workflow name can appear multiple times in the list (e.g., calling the same sync workflow with different parameters).

description (required)

Human-readable description for this workflow step.

  description: Analyze user question and search for relevant information

condition (optional)

Python expression evaluated at runtime. If it evaluates to False/None, the workflow step is skipped.

# Simple null check
condition: $.get('document_id') is not None

# Boolean check
condition: $.get('event_exists') is True

# Combined conditions
condition: $.get('document_id') is not None and $.get('reasoning_status') is True

# Check nested dict value
condition: $.get('chat_reasoning', {}).get('is_find_faq') is True

# Check enum value
condition: $.get('instructions_reasoning', {}).get('action') == 'list'

# Check value in list
condition: $.get('instructions_reasoning', {}).get('action') in ['enable', 'disable']

# Check season type
condition: "$.get('season_type') == 'PST'"

# Multiple complex conditions
condition: $.get('event_exists') is True and $.get('output-documents') is not None

# Multiline condition (use pipe)
condition: |
  (
    $.get('document_id') is not None and
    $.get('instructions_reasoning', {}).get('action') == 'list'
  )

inputs (optional)

Key-value pairs passed to the workflow. Values are Python expressions evaluated against the agent's current state.

inputs:
  # Pass from context-agent
  thread_id: $.get('thread_id')
  input_message: $.get('messages', [])

  # Pass from previous workflow outputs
  document_id: $.get('document_id')
  reasoning: $.get('reasoning')

  # Pass literal string values (quoted within quotes)
  season_type: "'REG'"
  output_status: "'idle'"
  data_type: "'schedule.json'"

  # Pass computed values
  nfl_season_week: "str(int($.get('week_sequence', 1)) + 1)"
  season_year: "str($.get('season_year', 2025))"

  # Pass with defaults
  max_queries: "$.get('max_queries', 3)"
  language: "$.get('language', 'en')"
  content_types: $.get('content_types', ['meme', 'stats', 'quiz'])

  # Pass from context (agent-level state)
  country: context.get('coverage-markets-country')

outputs (optional)

Key-value pairs extracted from the workflow response and merged into the agent's state. These become available to subsequent workflows via $.get().

outputs:
  # Extract simple values
  reasoning: $.get('reasoning')
  document_id: $.get('document_id')

  # Extract with defaults
  suggestions: $.get('suggestions', [])
  user_profile: $.get('user_profile')

  # Check workflow execution status
  workflow-status: $.get('workflow-status')
  reasoning_status: $.get('workflow-status') == 'executed'
  sync_status: "$.get('workflow-status', False)"

  # Extract nested values
  response_text: $.context.get('response_text', '')
  content: $.context.get('response_text', '')

  # Convert types
  week_sequence: "str($.get('week_sequence'))"

  # Return static values
  objects: []
  stream: true

foreach (optional)

Loops the workflow execution over a list of items. Each iteration receives the current item.

# Basic foreach
foreach:
  name: competitionItem     # Variable name for each item
  expr: $                   # Expression context (usually $)
  value: $.get('coverage-markets-mapping')  # List to iterate over

---

Agent Type Patterns

Chat Agent (Conversational)

On-demand agent triggered by user messages. Manages conversation threads.

agent:
  name: my-chat-executor
  title: My Chat - Executor
  description: AI-powered chat assistant
  context:
    status: "inactive"
  context-agent:
    thread_id: $.get('thread_id', None)
    messages: $.get('messages', [])
  workflows:
    - name: my-chat-reasoning
      description: Analyze user message and determine intent
      condition: $.get('messages') is not None and len($.get('messages')) > 0
      inputs:
        thread_id: $.get('thread_id')
        input_message: $.get('messages', [])
      outputs:
        reasoning: $.get('reasoning')
        document_id: $.get('document_id')
        reasoning_status: $.get('workflow-status') == 'executed'

    - name: my-chat-response
      description: Generate response using LLM
      condition: $.get('document_id') is not None and $.get('reasoning_status') is True
      inputs:
        document_id: $.get('document_id')
        reasoning: $.get('reasoning')
      outputs:
        response_text: $.get('response_text')
        suggestions: $.get('suggestions', [])
        response_content: $.get('response_content')
        response_status: $.get('workflow-status') == 'executed'

    - name: my-chat-update
      description: Update conversation thread
      condition: $.get('document_id') is not None and $.get('response_status') is True
      inputs:
        document_id: $.get('document_id')
        response_content: $.get('response_content')
        response_text: $.get('response_text')
        suggestions: $.get('suggestions', [])
      outputs:
        thread_id: $.get('document_id')
        workflow-status: $.get('workflow-status')
        response_text: $.context.get('response_text', '')
        content: $.context.get('response_text', '')
        objects: []
        suggestions: $.context.get('suggestions', [])

Key characteristics:

• context.status: "inactive" — activated on-demand
• context-agent receives thread_id and messages
• Typical flow: reasoning → response → update
• Final outputs use $.context.get() to access agent state

Scheduled Agent (Jobs)

Runs on a schedule via Celery Beat. Dispatches skills or agents at defined intervals or cron expressions.

agent:
  name: my-data-scheduler
  title: My Data - Scheduler
  description: Periodically sync data from external APIs
  context:
    status: "active"
  jobs:
    # Interval: run every 30 seconds
    - name: "sync-data"
      enabled: true
      type: "skill"
      target: "my-sync-skill"
      interval: 30
      context:
        data_type: "latest"

    # Cron: run daily at 03:00
    - name: "daily-cleanup"
      enabled: true
      type: "agent"
      target: "my-cleanup-agent"
      cron: "0 3 * * *"
  workflows:
    - name: my-sync-data
      description: Sync latest data
      outputs:
        sync_status: "$.get('workflow-status', False)"

    - name: my-process-data
      description: Process synced data
      condition: "$.get('sync_status') == 'executed'"
      inputs:
        data_type: "'latest'"
      outputs:
        process_status: "$.get('workflow-status', False)"

Key characteristics:

• status: "active" required — scheduler only evaluates active agents
• jobs array defines scheduling rules (interval or cron)
• Each job targets a skill or agent by name
• context in the job is passed as context-agent to the target
• No context-agent on the agent itself (no user input)
• Often uses foreach for batch processing

Legacy: context.config-frequency: N (APScheduler) is deprecated. Use jobs with interval or cron instead.

One-Shot Agent (Single Request)

Processes a single request without thread management.

agent:
  name: my-generator
  title: My Generator
  description: Generate content based on input parameters
  context-agent:
    team_a: $.get('team_a')
    team_b: $.get('team_b')
    language: $.get('language', 'en')
  workflows:
    - name: my-generate-content
      description: Generate content comparing inputs
      inputs:
        team_a: "$.get('team_a')"
        team_b: "$.get('team_b')"
        language: "$.get('language', 'en')"
      outputs:
        workflow-status: "$.get('workflow-status')"
        content: "$.get('content')"
        metadata: "$.get('metadata')"

Key characteristics:

• No context block (or no status/config-frequency)
• context-agent receives specific parameters
• Usually a single workflow or simple chain
• Returns results directly

Pipeline Agent (Multi-Step Processing)

Chains multiple workflows sequentially, each building on previous results.

agent:
  name: my-pipeline-agent
  title: My Pipeline Agent
  description: Multi-step content pipeline with generation, media, and delivery
  context-agent:
    document_id: "$.get('document_id')"
  workflows:
    - name: my-pipeline-generate
      description: Generate text content
      inputs:
        document_id: "$.get('document_id')"
      outputs:
        document_id: "$.get('document_id')"
        workflow-status: "$.get('workflow-status')"

    - name: my-pipeline-audio
      description: Generate audio from content
      condition: "$.get('document_id') is not None"
      inputs:
        document_id: "$.get('document_id')"
        voice_id: "$.get('voice_id')"
      outputs:
        document_id: "$.get('document_id')"
        workflow-status: "$.get('workflow-status')"
        audio_path: "$.get('audio_path')"

    - name: my-pipeline-image
      description: Generate cover image
      condition: "$.get('document_id') is not None"
      inputs:
        document_id: "$.get('document_id')"
      outputs:
        document_id: "$.get('document_id')"
        workflow-status: "$.get('workflow-status')"
        image_url: "$.get('image_url')"

    - name: my-pipeline-deliver
      description: Package and deliver final content
      condition: "$.get('document_id') is not None"
      inputs:
        document_id: "$.get('document_id')"
      outputs:
        workflow-status: "$.get('workflow-status')"

Key characteristics:

• Each workflow passes document_id forward
• All steps after the first have condition: "$.get('document_id') is not None"
• Each step enriches the same document

Branching Agent (Conditional Routing)

Routes execution based on reasoning output. Different workflows run depending on conditions.

agent:
  name: my-branching-executor
  title: My Branching - Executor
  description: Routes to different workflows based on intent analysis
  context:
    status: "inactive"
  context-agent:
    thread_id: $.get('thread_id', None)
    messages: $.get('messages', [])
  workflows:
    # Step 1: Analyze intent (always runs)
    - name: my-reasoning
      description: Analyze input and determine action
      inputs:
        input_message: $.get('messages', [])
        thread_id: $.get('thread_id')
      outputs:
        reasoning: $.get('reasoning')
        document_id: $.get('document_id')

    # Branch A: Search FAQ
    - name: my-search-faq
      description: Search FAQ knowledge base
      condition: $.get('document_id') is not None and $.get('reasoning', {}).get('is_faq') is True
      inputs:
        document_id: $.get('document_id')
      outputs:
        faq_results: $.get('faq_results')

    # Branch B: Search Events
    - name: my-search-events
      description: Search upcoming events
      condition: $.get('document_id') is not None and $.get('reasoning', {}).get('search_type') == 'events'
      inputs:
        document_id: $.get('document_id')
      outputs:
        event_results: $.get('event_results')

    # Branch C: Search Markets
    - name: my-search-markets
      description: Search market data
      condition: $.get('document_id') is not None and $.get('reasoning', {}).get('is_markets') is True
      inputs:
        document_id: $.get('document_id')
      outputs:
        market_results: $.get('market_results')

    # Final: Generate response (always runs if document exists)
    - name: my-response
      description: Generate final response
      condition: $.get('document_id') is not None
      inputs:
        document_id: $.get('document_id')
        faq_results: $.get('faq_results')
        event_results: $.get('event_results')
        market_results: $.get('market_results')
      outputs:
        response_text: $.get('response_text')

Key characteristics:

• First workflow (reasoning) always runs
• Middle workflows have mutually exclusive or independent conditions
• Final workflow collects all results regardless of which branches ran
• Non-executed branches pass None forward (handled by defaults)

Foreach Agent (Batch Processing)

Iterates over a list of items, running a workflow for each.

agent:
  name: my-batch-processor
  title: My Batch Processor
  description: Process multiple items in batch with foreach
  context:
    config-frequency: 10
  workflows:
    # Step 1: Load configuration
    - name: my-load-config
      description: Load processing configuration
      outputs:
        item_list: $.get('item_list')
        processing_params: $.get('processing_params')

    # Step 2: Process each item
    - name: my-process-item
      description: Process individual items
      foreach:
        name: currentItem
        expr: $
        value: $.get('item_list')
      inputs:
        param: context.get('processing_params')

Key characteristics:

• foreach.name — variable name for current item in the loop
• foreach.expr — expression context (typically $)
• foreach.value — the list to iterate over
• Use context.get() inside foreach to access agent-level state

---

Expression Syntax

All expressions use Python syntax with $.get() for state access.

# Access current state
$.get('field_name')
$.get('field_name', 'default_value')

# Access nested values
$.get('reasoning', {}).get('action')

# Access agent context (in final workflow outputs)
$.context.get('response_text', '')

# Access agent context (inside foreach inputs)
context.get('coverage-markets-country')

# Type conversion
str($.get('week_sequence'))
int($.get('week_sequence', 1))

# String operations
"str($.get('season_year', 2025))"

# Computed values
"str(int($.get('week_sequence', 1)) + 1)"

# Ternary/conditional expressions
"str($.get('pst_week')) if $.get('season_type') == 'PST' else str($.get('week_sequence', 1))"

# List operations
len($.get('documents', []))
$.get('documents')[0].get('value', {})

# Boolean comparisons
$.get('workflow-status') == 'executed'
$.get('workflow-status', 'skipped') == 'executed'

# Literal string values (must double-quote)
"'REG'"
"'idle'"
"'schedule.json'"

---

Naming Conventions

---

Common Mistakes