Quickstart

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.

curl (recommended)
uv
pipx
pip

curl -fsSL https://sirenspec.dev/install.sh | sh

Detects your environment and picks the best available installer (uv → pipx → pip).

uv tool install sirenspec

pipx install sirenspec

pip install sirenspec

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.

Getting Started

Core Concepts

Reference

Resources

Installation

Set Your API Key

Initialize Your Project

Run It

Start from Scratch

Override the Input at Runtime

Validate Without Running

Try a Multi-Agent Pipeline

Next Steps

YAML Reference

Providers

Guardrails

CLI Reference

​Installation

​Set Your API Key

​Initialize Your Project

​Run It

​Start from Scratch

​Override the Input at Runtime

​Validate Without Running

​Try a Multi-Agent Pipeline

​Next Steps

YAML Reference

Providers

Guardrails

CLI Reference

Installation

Set Your API Key

Initialize Your Project

Run It

Start from Scratch

Override the Input at Runtime

Validate Without Running

Try a Multi-Agent Pipeline

Next Steps