Build agents at the speed of spec

Define workflows in YAML. Wire tools in any language. Run from one command.

terminal
$ specrun init my-agent
✓ Created flow.json
✓ Created tools/example_tool.sh
$ specrun run flow.json --tools-dir tools --input '{"query": "quantum computing"}'
▸ Starting flow: research-assistant
▸ Agent calling: web_search
▸ Flow complete
{"result": "Quantum computing uses..."}
Open Agent Spec compliantv0.1.0-beta4

See it in action

nodes:
  - name: researcher
    type: AgentNode
    agent:
      tools:
        - web_search
        - calculator
    llm:
      type: OpenAiConfig
      model: gpt-4o

Flow

Research Assistant

type: Agent
name: math-helper
llm:
  type: VllmConfig
  model: meta-llama/Llama-3.1-8B
tools:
  - name: multiplication_tool
    inputs:
      - a: integer
      - b: integer

Agent

Math Homework Agent

type: Agent
name: rag-expert
systemPrompt: |
  You are an expert in
  {{domain_of_expertise}}.
tools:
  - name: rag_tool
    inputs:
      - query: string

Agent

RAG Agent

type: Agent
name: it-assistant
llm:
  type: VllmConfig
  model: meta-llama/Llama-3.1-8B
systemPrompt: |
  You are an IT assistant.
  Help users troubleshoot.

Agent

IT Assistant

Three steps to your first agent

01

Define

Describe your workflow in YAML or JSON using the Open Agent Specification.

# flow.yaml
nodes:
  - name: start
    type: StartNode
  - name: agent
    type: AgentNode
    agent:
      tools: [web_search]
    llm:
      type: OpenAiConfig
      model: gpt-4o
  - name: end
    type: EndNode
02

Wire Tools

Tools are standalone executables. Write them in any language — no SDK required.

#!/usr/bin/env python3
import sys, json

args = json.load(sys.stdin)
query = args.get("query", "")

results = search(query)

json.dump({
  "results": results
}, sys.stdout)
03

Run

Compile, validate, and execute — all from one command.

$ specrun run flow.yaml \
    --tools-dir ./tools \
    --input '{"query": "quantum computing"}'

▸ Starting flow: research-assistant
▸ Agent calling: web_search
▸ Agent calling: web_search
▸ Flow complete

{"result": "Quantum computing uses..."}

Everything you need

Declarative Workflows

Define multi-step agent flows in YAML/JSON. No boilerplate code.

Graph-Based Execution

Flows compile into directed graphs with control and data flow edges, validated before running.

LLM Tool-Calling Loop

Agents autonomously call tools in a loop until the task is done. Up to 10 rounds per node.

Any-Language Tools

Tools are subprocesses that speak JSON over stdin/stdout. Use Bash, Python, Go — anything.

Provider Agnostic

Works with OpenAI, vLLM, Ollama, or any OpenAI-compatible endpoint.

Interactive Chat Mode

Debug and explore flows with persistent multi-turn conversations via --chat.

From zero to agent in 30 seconds

# Install via npm
$ npm install -g @specrun/cli

# Or via Homebrew
$ brew install spichen/tap/specrun

# Create and run your first agent
$ specrun init my-agent
$ specrun run my-agent/flow.json --tools-dir my-agent/tools
Get Started

Questions?