Introduction

heddle needs no SDK. Most agent frameworks are libraries: you install one, import it, and assemble the graph in code, so the agent ends up depending on the library's abstractions. heddle inverts that. The flow is a document you write, and heddle is a runtime you point at it. Nothing in the document imports anything, and nothing in your project depends on heddle's types.

The document is an Open Agent Specification flow, in YAML or JSON. It names nodes, the edges between them, the model each agent calls, and the tools they may use.

One document runs two ways. heddle run executes it on your machine; heddle-server serves it over HTTP with the run streamed back as it happens. There is no rewrite between them and no separate deployment format: the same file, pointed at by a different program.

Quick start

npm install -g @heddle-run/cli

Scaffold a project, then run it:

heddle init my-agent
cd my-agent
heddle run flow.json --tools-dir tools --input '{"query": "hello"}'

--input is JSON handed to the flow as its starting state. The scaffolded prompt references {{query}}, so a run without it sends the placeholder to the model unchanged.

What happens when you run it

document → parse → validate spec → compile graph → validate graph → execute

There are two validation passes and they check different things. The first reads the document against the Agent Spec schema, before heddle knows what a graph is. The second runs after compilation and checks the graph itself: that every node is reachable, that every branch a node can take has an edge, and that the flow terminates.

heddle validate runs everything up to execution, so it is the whole of that pipeline minus the model calls.

Where to go next