Code Steps

Execute custom code logic with access to tools and integrations.

Overview

Code steps let you run custom logic within your workflow. The AI can generate code based on a prompt, or you can write code manually. Code steps have access to Magpai tools and external integrations.

Advanced feature: Code steps are best for complex transformations, calculations, or logic that can't be easily expressed as AI prompts.

Configuration

Property	Type	Description
name	string	Display name for the step
prompt	string	Description of what code should do
code	string?	The code to execute (generated or manual)
providers	string[]?	External service providers to enable
disabled	boolean?	Skip this step when running

How Code Steps Work

1. Code Generation

If no code is provided, AI generates code based on the prompt. You can also write code manually or edit the generated code.

2. Execution Environment

Code runs with access to Magpai tools and any enabled external integrations. Generated files are automatically uploaded to cloud storage.

3. Error Recovery

If code fails, the system automatically retries with fixes (up to 3 attempts). This helps handle edge cases and unexpected data.

4. Output

Code results become inputs for subsequent steps. Outputs are sanitized before storage.

Example Configuration

{
  "id": "process-data",
  "type": "code",
  "name": "Process Survey Results",
  "prompt": "Parse the survey CSV data and calculate average scores for each category. Output a summary object with category names and their averages.",
  "providers": ["google-sheets"]
}

What Code Steps Can Do

Data transformation - Parse, filter, aggregate data
Calculations - Complex math, statistics, formulas
File generation - Create CSVs, PDFs, images
API integration - Call external services via providers
Custom logic - Conditional branching, loops, validation

Tool & Provider Access

Code steps can access the same tools available to prompt steps, plus any external providers you enable.

Access Type	Examples
Magpai Tools	File read/write, data operations
External Tools	Integrations configured for your team
Providers	Google Sheets, Slack, etc.

When to Use Code Steps

Use code steps when:

You need precise control over data transformations
The logic is too complex for a prompt instruction
You need deterministic results (same input → same output)
You're working with structured data formats
You need to call specific APIs or services

Prompt Steps vs Code Steps

Aspect	Prompt Step	Code Step
Best for	Creative, flexible tasks	Precise, deterministic logic
Output	May vary between runs	Consistent for same input
Complexity	Handles ambiguity well	Requires explicit logic

Best Practices

Write clear, detailed prompts describing exactly what the code should do
Specify input and output formats explicitly
Review generated code before relying on it in production
Use code steps sparingly - prefer prompt steps when possible
Test with various inputs to ensure robustness

Prompt Steps - AI-powered processing alternative
Building Workflows - When to use which step type
Integrations - Setting up external providers