Why kdeps?
Workflow mode runs an AI workload in production as an API, a chatbot or a background job. Agent mode uses the same file when the model should choose the steps. You pay for the hardware it runs on.
The six products
kdeps is a small number of bounded pieces - workflow, agent, agencies, LLM server, deploy, and the optional registry. Most people need one or two. The Which product do you need? table matches each to a task.
A workflow.yaml is the pipeline you deploy. kdeps with no path is the REPL against a local model, and it needs no YAML and no Docker. The registry is optional - it shares agents by name, not a step in building or running your own. The two modes below apply to whichever you use.
Deterministic by design
An LLM is probabilistic - ask Claude or GPT the same question twice and you can get two different answers. kdeps workflow mode wraps that in a deterministic shell: the same request always takes the same path through the same resources, requires: fixes the order, validations fire before any model is called, and the output is shaped to a fixed schema. The model's wording varies; the pipeline around it does not.
If the input is wrong, the workflow fails fast with a clear error instead of hallucinating a response. Output is reproducible in structure, auditable, and safe to run unattended - that is what makes kdeps suitable for production, not just demos.
Agent mode is the opposite: there the model decides which resources run and in what order.
Git-native
The YAML is the behavior spec. What your appliance does - which model it calls, what it validates, which steps run in what order, the shape of the response - is entirely defined by the workflow.yaml and resources/*.yaml in your repository. There is no database of agent state, no proprietary project file, no web console that owns the source of truth. Change the YAML, commit, and the appliance behaves differently. Your git history is the changelog of the agent's behavior.
The one thing that lives outside the repo is the backend binding - the LLM backend, model names, API keys, and database connections in ~/.kdeps/config.yaml and environment variables. That is deliberate: the same repo runs against a local llamafile on your laptop and a cloud model in production with no diff. Your agent's logic is in git; only its wiring to a specific model is not.
The core loop needs nothing but git and the kdeps binary: edit YAML, commit, kdeps run or kdeps bundle build. Everything below builds on that.
Review, version, build, share
- Review an agent change the way you review code - a diff of resources, validations, and prompts in a pull request.
- Version with a git tag. A tag is a release;
kdeps validateandkdeps bundle buildrun against any checkout or tag. - Build reproducibly in CI:
kdeps validate->kdeps bundle build->docker push, triggered on tag. The same commit yields the same appliance, runtime and model pinned. - Share, optionally. kdeps registry is a convenience layer for installing and publishing agents and components by name -
kdeps install owner/repopulls straight from a GitHub repo, no registry entry required. You never need it to build or deploy your own agent.
The git component also lets an agent read and write repository state as part of its pipeline - status, diff, log, commit, branch.
Two modes, one workflow file
Workflow mode is for production: inputs are validated, resources execute in a fixed order, output is predictable and auditable. Agent mode is for exploration: the LLM decides which workflows to call and in what order, with each workflow running as a complete pipeline.
Same workflow.yaml, no rewrites, no re-config.
Agencies
kdeps agencies let you compose multiple specialized agents into a single system. Each agent has its own model, resources, and logic. They communicate via the agent: resource type, which runs another agent's full pipeline and returns its output - every step is version-controlled, testable, and independently deployable.
Built to last
Model APIs deprecate and SDK interfaces change. kdeps reduces how many of those moving parts can break a running workload. The thing you archive is the built appliance - the Docker image, ISO, or self-contained binary you produce with kdeps bundle. It pins the kdeps runtime, the executors, and (for local models) the model itself into one frozen unit. Redeploying that image later runs the same runtime and model, with no live dependency on a vendor API.
What stays stable
What stays stable:
- Local LLMs do not break underneath you. With Ollama or any self-hosted model, the interface changes only when you update it. No vendor deprecation notices, no sunset dates.
- The backend is decoupled from the workflow. Cloud model names live in
~/.kdeps/config.yaml, not inworkflow.yaml. When a model is deprecated, you change one line in config; the workflow is untouched. - Your logic is code you own. SQL, LLM prompts, Python, exec, email, inter-agent calls - these change when you change them.
What you should expect to maintain
What you should expect to maintain:
| Thing | Why it moves | What to do |
|---|---|---|
The workflow.yaml schema | kdeps does not carry legacy schema shims - a newer kdeps binary may reject an older file. apiVersion: kdeps.io/v1 marks the current schema, not a frozen one. | Keep the source YAML with the image; re-validate with kdeps validate before upgrading the runtime, or just keep running the built image. |
http_request targets | External APIs change schema, auth, endpoints | Target a versioned path (/v2/users, not /users) |
The guarantee is not that your YAML runs forever on any future kdeps. It is that the appliance you ship is a self-contained unit you can freeze, archive, and redeploy without a live dependency on any vendor.
Who it is for
| Role | Use case |
|---|---|
| Developers | Ship AI features into products (APIs, bots, internal tools) without glue code |
| Operations teams | Automate repetitive work: log analysis, PR reviews, triage, ticket creation, incident messaging |
| SMEs without an AI hire | Add AI to existing business processes and APIs with near-zero code and no recurring AI bill |
| Marketing and growth | Content pipelines, SEO automation, campaign reporting |
| Regulated and public-sector teams | Meet data-residency rules - self-hosted LLM and coding agent in the region you choose |
| Any team | Replace a human clicking through tabs and copy-pasting between tools |
Concretely: log-file analysis, automated code reviews, JIRA ticket creation from an alert, an incident summary posted to MS Teams - each is a workflow that calls a model and one or two external APIs, deployed as one image.
The name
kdeps is short for knowledge dependencies. It grew out of earlier work on Kartographer, a graph library for resolving dependent nodes: knowledge - from a model, a machine, or a person - can be represented and orchestrated as a graph. A kdeps workflow is exactly that, a dependency graph of resources, run in order.
Built on
kdeps is built on two small open-source projects developed alongside it. Both are standalone Go tools you can use on their own.
| Project | What it does | Where kdeps uses it |
|---|---|---|
| kdeps/kartographer | A graph library for resolving dependent nodes. | The requires: DAG that orders every workflow; the reference/topic graph behind search_local graphBoost and skill-library linking. |
| kdeps/turo | Reduces prose to its content words to cut LLM input tokens - "point more, token less." | The optional prompt reducer for agent mode: when the turo binary is on PATH, kdeps pipes system preamble, input, tool results, and history through it before every model call. |
See also
- Quickstart - build your first workflow API
- Run locally - agent REPL in 30 seconds
- Data sovereignty - your prompts stay on your servers
- Load a workflow as a tool - same file, agent mode
- Workflow mode - deterministic DAG pipelines
- Agent mode - autonomous LLM loop