v0.1 — AI workflow specification

AI workflows your whole team can read.

Define your AI workflows in plain language. Readable by everyone on your team and enforceable in production.

Python 3.11+ required

Read the Docs View on GitHub Sponsor

MIT LicensedOpenAI · Anthropic · OllamaZero boilerplateBuilt-in guardrails

Features

YAML-first. Zero boilerplate.

Stop wrestling with framework abstractions. Define exactly what you want your agents to do — in plain text.

The whole workflow on one screen

Agents, nodes, edges, and guardrails — one file anyone on the team can open, read, and review. Your PM can audit it. Your security lead can verify the cost cap is there. Your git diffs make sense.

Agent Factory

Point for_each at any runtime list and it spawns one agent per item. Each spawned agent can be a swrm, so you get a parallel fan-out for every item — no loop code, no manual wiring.

Guardrails in the file, not the footnotes

Cost caps, PII detection, and injection protection live right next to your agent definition — one line each. If the cap isn't there, it's visible. If it is, anyone can confirm it.

Swrm Fan-out

Run multiple agents concurrently with a single type: swrm node. Define a synthesis step to combine outputs. Concurrency without callbacks.

Conditional Edges

Route workflow execution with when: conditions on edges. Branch on LLM output, context values, or any runtime expression.

CLI-first

Run sirenspec run workflow.yaml and get a JSON trace on stdout. Pipe to jq. Drop into any CI/CD pipeline that can run a shell command.

How It Works

Compose. Run. Ship.

workflow.yaml

1version: "0.1"

3agents:

4 researcher:

5 model: "anthropic:claude-haiku-4-5-20251001"

6 system: "You are a research assistant."

7 guardrails: ["injection", "length"]

9 writer:

10 model: "openai:gpt-4o-mini"

11 system: "You are a technical writer."

13nodes:

14 research:

15 agent: researcher

16 writes: working.research

18 draft:

19 agent: writer

20 prompt: |

21 Research: {{ working.research }}

22 Write about: {{ inputs.topic }}

24edges:

25 - from: research

26 to: draft

Define agents in YAML

Give each agent a model, a system prompt, and optional guardrails. Mix providers freely — one file, any backend.

Compose nodes and edges

Chain agents with nodes. Wire up data flow with template expressions like {{ working.research }}. Add conditional edges with when:.

Run anywhere

sirenspec run workflow.yaml --input 'topic' — that's it. Get a JSON trace back. Pipe it, log it, test it.

$ sirenspec run workflow.yaml --input "AI orchestration"
# → JSON execution trace to stdout

vs the Field

Readable by default. Auditable by anyone.

The same two-agent pipeline, written four ways. You decide which one you'd rather maintain.

SirenSpec — workflow.yaml23 lines

1version: "0.1"

3agents:

4 researcher:

5 model: "anthropic:claude-haiku-4-5"

6 system: "Research assistant."

7 writer:

8 model: "openai:gpt-4o-mini"

9 system: "Technical writer."

11nodes:

12 research:

13 agent: researcher

14 writes: working.research

15 draft:

16 agent: writer

17 prompt: |

18 Based on {{ working.research }},

19 write about {{ inputs.topic }}

21edges:

22 - from: research

23 to: draft

43 lines

pipeline.py

from langchain_openai import ChatOpenAI
from langchain_anthropic import ChatAnthropic
from langchain_core.prompts import (
    ChatPromptTemplate,
)
from langchain_core.output_parsers import (
    StrOutputParser,
)
from langchain_core.runnables import (
    RunnablePassthrough,
)

researcher = ChatAnthropic(
    model="claude-haiku-4-5"
)
writer = ChatOpenAI(model="gpt-4o-mini")

research_prompt = ChatPromptTemplate.from_messages([
    ("system", "Research assistant."),
    ("human", "{topic}"),
])
write_prompt = ChatPromptTemplate.from_messages([
    ("system", "Technical writer."),
    ("human", "Research: {research}\nTopic: {topic}"),
])

research_chain = (
    research_prompt | researcher | StrOutputParser()
)
write_chain = (
    RunnablePassthrough.assign(
        research=lambda x: research_chain.invoke(
            {"topic": x["topic"]}
        )
    )
    | write_prompt
    | writer
    | StrOutputParser()
)

result = write_chain.invoke(
    {"topic": "AI orchestration"}
)

Capability	SirenSpec← you are here	Big Agent Frameworks	Raw SDK

Workflow format	YAML	Python	Python
Lines for 2-agent pipeline	~23	~35+	~40+
Human-readable by default
Git-diffable workflows
Built-in guardrails
Multi-provider in one file
Fan-out concurrency
CLI-first execution
Open source (MIT)
Audit trail non-engineers can read

OPEN SOURCE · YAML-FIRST · BUILDER TOOLS

AI orchestration you can actually read

SirenSpec is a workflow format and runtime for AI pipelines. Write it in YAML. Version it in git. Hand it to anyone on your team and they'll understand it — no Python required.

Read the Docs View on GitHub

Built independently and open source.Support development