Skip to main content

​
Installation

The fastest way to install SirenSpec is the one-line install script: 
curl -fsSL https://sirenspec.dev/install.sh | sh
This detects your environment and uses the best available installer (uv → pipx → pip). Python 3.11 or later is required.

​
Set Your API Key

SirenSpec reads provider credentials from environment variables. Set at least one: 
export OPENAI_API_KEY=sk-...
# or
export ANTHROPIC_API_KEY=sk-ant-...

​
Initialize Your Project

Run sirenspec init to scaffold a workflow interactively. It asks you to pick a template and a provider, then writes a workflow.yaml and a .env.example ready to run: 
sirenspec init

Welcome to SirenSpec! Let's scaffold a new workflow.

Choose a template:
  1. simple-agent          — Single agent that answers a question
  2. sequential-pipeline   — Two agents in sequence
  ...

Template [1]: 1

Choose a provider:
  1. openai
  2. anthropic

Provider [1]: 1

Enable guardrails? (injection + length) [Y/n]: Y

✓ workflow.yaml created
✓ .env.example created

Next steps:
  Copy .env.example → .env and add your API key
  sirenspec validate workflow.yaml
  sirenspec run workflow.yaml

​
Run It

sirenspec run workflow.yaml
By default, SirenSpec displays a streaming view of node execution: 
╭─ answer ──────────────────────────────╮
│ Paris is the capital of France.       │
╰────────────────────────────────────────╯
  ↓ output.reply

Run complete  │  1 node  │  24 tokens  │  cost unavailable (pricing not configured)
To see the full JSON execution trace, use the --trace flag: 
sirenspec run workflow.yaml --trace

​
Start from Scratch

Prefer writing YAML yourself? Create a file named hello.yaml:
hello.yaml
version: "0.1"

agents:
  assistant:
    model: "openai:gpt-4o-mini"
    system: "You are a helpful assistant. Answer questions clearly and concisely."

nodes:
  answer:
    agent: assistant
    writes: output.reply

input:
  message: "What is the capital of France?"
Then run it: 
sirenspec run hello.yaml

​
Override the Input at Runtime

Use --input (or -i) to pass a message from the command line, overriding any input.message defined in the YAML: 
sirenspec run hello.yaml --input "What is the speed of light?"

​
Validate Without Running

Check that your workflow is valid without making any API calls: 
sirenspec validate hello.yaml
# ✓ hello.yaml is valid (1 agent, 1 node)

​
Try a Multi-Agent Pipeline

The Cookbook includes ready-to-run workflows. Clone the repo and try: 
git clone https://github.com/sirenspec/sirenspec.git
cd sirenspec

# Sequential pipeline: classify → reply
sirenspec run docs/cookbook/sequential-pipeline/workflow.yaml --input "I need help with my order"

# Conditional branching: triage → handle_refund or handle_general
sirenspec run docs/cookbook/conditional-pipeline/workflow.yaml --input "I want a refund"

​
Next Steps

YAML Reference

Learn every field available in a workflow file.

Providers

Configure OpenAI, Anthropic, and Ollama.

Guardrails

Understand the built-in guardrail system.

CLI Reference

Full CLI command documentation.