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
