I rewrote a big slice of OrKa’s documentation after some painfully honest feedback. The summary of that feedback was clear: parts of the docs sounded like marketing, not engineering. They were more about what OrKa could be than how to actually build with it.
So I did what engineers do. I deleted more words than I added, I replaced adjectives with examples, and I wrote a single source of truth for the YAML surface that OrKa exposes.
This article walks through what changed, why it changed, and how to use the new reference to assemble real cognitive flows. No hype. A few jokes. Lots of YAML.
If you just want the index, it is here:
AGENT_NODE_TOOL_INDEX.md
https://github.com/marcosomma/orka-reasoning/blob/master/docs/AGENT_NODE_TOOL_INDEX.md
Spoiler: the goal is not to impress you. It is to help you ship something traceable and reproducible, then help you debug it when it misbehaves. If you have ever spent an hour chasing a missing indent in YAML, consider this my small apology in advance.
What OrKa is, in one paragraph
OrKa is a modular cognition orchestrator. You define a graph of small, purpose-built agents in YAML. The orchestrator runs them with clear routing, optional parallelism, explicit joins, and observable traces. Agents can read and write to memory layers, call tools, or hand off to routers that decide the next step. You get full logs of inputs, outputs, decisions, and timing so you can reproduce runs or replay them.
Not a chatbot kit. Not prompt spaghetti. A build surface for agentic reasoning with observability on by default.
Why the docs needed a reset
As OrKa’s capabilities grew, the YAML surface grew with it. More agent types. More node types. Tools. Memory writers. Confidence-guided routing. That is good for power users, but it raises the floor for new users. If the docs do not scale at the same pace, you get a gap where people try OrKa, hit a wall, and leave.
The honest feedback I received said exactly that. The docs were sometimes vague. They compared OrKa to other tools instead of explaining OrKa’s own model clearly. They also blurred infrastructure choices with features. Using Redis or Kafka for transport is an implementation detail, not a selling point. It belongs in Design Notes, not the front page.
So I moved the center of gravity to a single YAML-first reference for Agents, Nodes, and Tools. One place to check what a field means, what is required, what is optional, and what a minimal example looks like. That is the AGENT_NODE_TOOL_INDEX.
Principles that guided the rewrite
- Clarity beats coverage. If a field is not documented, do not use it.
- One concept per page section. Agent types are separate from Node types, and both are separate from Tools.
- Examples must be runnable or trivially adaptable.
- Defaults are explicit, not implied by prose.
- Errors are first-class. Common failure modes get copy-paste fixes.
- Infrastructure is described as infrastructure. It is not a feature.
- Terminology is consistent: Agent, Node, Tool, Orchestrator, Memory layer, Router.
Glossary, one line each
- Agent: a unit that transforms inputs into outputs, usually by prompting a model or running a deterministic function.
- Node: a control primitive that shapes the flow, like forks, joins, routers, and memory writers.
- Tool: an external capability invoked by an agent, like HTTP or a database call.
- Orchestrator: the top-level execution contract that runs agents and nodes using a strategy.
- Memory layer: a scoped store with optional TTL and decay logic.
- Router: a node that decides the next step based on conditions or confidence distribution.
- Trace: the execution log that records inputs, outputs, decisions, and timing for replay.
What is still missing, and what is next
Docs are never done. The index is a strong baseline, but a few things are queued next.
- More runnable examples that link each agent and node back to one canonical flow.
- A compact Troubleshooting page that you can read like a grocery list.
- Better cross references between a tool call and the agents that tend to use it.
- A testable examples folder where every snippet is verified by CI.
How you can help
If you read the index and hit a gap, open an issue titled docs-gap: <file> <section> and paste the YAML you expected to work, along with the error you saw. If you are the kind of person who fixes typos while the kettle boils, send a PR. I will merge fast.
Closing thought
Good docs are not the dessert after the meal. They are part of the recipe. OrKa’s promise is simple: structured cognition you can observe and reproduce. The new reference is my attempt to make that promise concrete. It will keep improving as the system grows and as more people push on the rough edges.
Thanks to everyone who took the time to say the old docs read like marketing. That hurt a little, which was useful. The new ones read like engineering, which is the point.
If you made it this far, you deserve a final joke. The true output of any orchestrator is not the answer. It is the trace you can trust when the answer goes sideways.
Top comments (1)
Nice, loved the simplicity