Why kdeps?
kdeps exists because most AI tooling is built for prototyping, not for running unattended in production. This page applies to both workflow mode and agent mode - it explains why the two exist and when to reach for each. New to kdeps? Read What is kdeps? first.
The problem
There is no streamlined way to build AI agents and custom APIs - not chatbots - on open-source, self-hosted LLMs. Every project re-implements the same glue: retrieval, deterministic pipelines, typed inputs and outputs, dependency ordering, retries, validation, and a way to deploy the result anywhere.
kdeps is an AI Appliance Builder. You define what the agent does in YAML, and it runs as a self-contained unit - an HTTP API, a bot, a file processor - without a human in the loop. Everything a retrieval-augmented agent needs ships in one Dockerized image.
Because it runs open-source models by default (llamafile, Ollama, any HuggingFace GGUF), the built appliance has no per-token cost and no AI subscription - it is free to run forever, on or off the cloud. Cloud providers work too when you want them; the backend is one line of config, not baked into the workflow.
The six products
kdeps is a small number of bounded pieces - agent, workflow, 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.
You don't need Docker or even a YAML file to start: run kdeps and you have an agent REPL against a local model. Add a workflow.yaml when you want a deterministic pipeline you can deploy; reach for the rest as the work grows. The registry is optional - it is a way to share 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 or SMTP 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 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 registry 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: resource 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.
The same workflow.yaml works in both. You do not need to rewrite anything to switch.
Agencies
Single-agent workflows have limited scope. 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
Most AI tooling has a short half-life. A workflow written against a popular AI SDK in 2023 is unlikely to run without modification today. Model APIs deprecate. SDK interfaces churn. Libraries get abandoned.
kdeps reduces how many moving parts can break on you. 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. Hand that image to a new engineer years later and it runs exactly as it did the day you built it.
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:
| 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. |
httpClient: targets | External APIs change schema, auth, endpoints | Target a versioned path (/v2/users, not /users) |
browser: selectors | Website DOM changes without notice | Use stable selectors (ARIA roles, data attributes) over structural CSS |
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 |
| 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.
Innovation technology
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 codeIntelligence folder indexing, searchLocal 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
- Run locally - agent REPL in 30 seconds
- Quickstart - build your first workflow API
- Load a workflow as a tool - same file, agent mode
- Workflow mode - deterministic DAG pipelines
- Agent mode - autonomous LLM loop