​
Workflow Structure

Workflows in Machina Sports are defined in YAML format with the following key sections:

workflow:
  name: "workflow-name"                # Unique identifier for the workflow
  title: "Workflow Title"              # Human-readable title
  description: "Workflow description"  # Brief description of purpose
  context-variables:                   # Environment variables and API keys
    variable-name:
      key: "value"
  inputs:                              # Input parameters
    input-name: "$.get('parameter')"   # JSONPath expressions for inputs
  outputs:                             # Output parameters
    output-name: "$.get('result')"     # JSONPath expressions for outputs
  tasks:                               # Sequential tasks to execute
    - type: "task-type"                # Type of task (connector, document, prompt, mapping)
      name: "task-name"                # Unique name for the task
      description: "Task description"  # Brief description
      # Task-specific configuration

​
Task Types

Workflows support several task types to handle different operations:

​
Connector Tasks

Connect to external APIs and services to fetch or send data.

- type: "connector"
  name: "fetch-team-data"
  connector:
    name: "sportradar-nba"
    command: "get-teams/{team_id}/{data_type}"
    command_attribute:
      team_id: "$.get('team_id')"
      data_type: "'profile.json'"
  inputs:
    api_key: "$.get('api_key')"
  outputs:
    team-profile: "$"

​
Document Tasks

Perform operations on documents in the Machina database (search, update, bulk-save).

- type: "document"
  name: "load-similar-documents"
  config:
    action: "search"
    threshold-docs: 10
    search-vector: true
  connector:
    name: "machina-ai"
    command: "invoke_embedding"
    model: "text-embedding-3-small"
  inputs:
    name: "'content-snippet'"
    search-query: "$.get('messages')"
  outputs:
    documents: "$.get('documents')"

​
Prompt Tasks

Execute AI prompts to generate content or analyze data.

- type: "prompt"
  name: "chat-completions-prompt"
  connector:
    name: "machina-ai"
    command: "invoke_prompt"
    model: "gpt-4o"
  inputs:
    documents: "$.get('documents')"
    messages: "$.get('messages')"
  outputs:
    message: "$.get('choices')[0].get('message').get('content')"

​
Mapping Tasks

Transform data between different formats using predefined mappings.

- type: "mapping"
  name: "sportradar-nba-team-mapping"
  inputs:
    team_profile: "$.get('team-profile')"
  outputs:
    team_id: "$.get('team_id')"
    team_name: "$.get('team_name')"
    # Additional mapped fields

​
Conditional Logic

Tasks can include conditions to control execution flow:

- type: "document"
  name: "update-thread-document"
  condition: "$.get('document_id') is not None"
  # Task configuration

​
Real-World Example: Chat Completions Workflow

This example from our samples shows a workflow that processes chat messages and generates AI responses:

workflow:
  name: "chat-completions"
  title: "Chat Completions"
  description: "Workflow to execute a chat completion."
  context-variables:
    machina-ai:
      api_key: "$TEMP_CONTEXT_VARIABLE_SDK_OPENAI_API_KEY"
  inputs:
    messages: "$.get('messages', [])"
  outputs:
    message: "$.get('message')"
    workflow-status: "$.get('message') is not None and 'executed' or 'skipped'"
  tasks:
    # Load similar documents for context
    - type: "document"
      name: "load-similar-documents"
      config:
        action: "search"
        threshold-docs: 10
        search-vector: true
      connector:
        name: "machina-ai"
        command: "invoke_embedding"
        model: "text-embedding-3-small"
      inputs:
        name: "'content-snippet'"
        search-query: "$.get('messages')"
      outputs:
        documents: "$.get('documents')"

    # Generate response using AI
    - type: "prompt"
      name: "chat-completions-prompt"
      connector:
        name: "machina-ai"
        command: "invoke_prompt"
        model: "gpt-4o"
      inputs:
        documents: "$.get('documents')"
        messages: "$.get('messages')"
      outputs:
        message: "$.get('choices')[0].get('message').get('content')"

​
Common Workflow Patterns

​
Data Synchronization

Fetch data from external sources and store it in your Machina database.

​
Content Generation

Create AI-generated content based on sports data and user context.

​
Chat Processing

Handle user messages and generate contextually relevant responses.

​
Scheduled Tasks

Execute workflows at regular intervals using scheduler agents.

​
Next Steps

  • Explore Agents to understand how to schedule workflows
  • Learn about Connectors to integrate data sources
  • Review Mappings to transform data between formats
  • See Prompts to optimize AI outputs