Frequently asked questions ​

Common questions about kdeps installation, usage, and architecture.

Is kdeps free? ​

Yes. kdeps is open source under the Apache 2.0 license. The CLI, engine, and all resources are free to use.

What is the difference between workflow mode and agent mode? ​

Workflow mode (kdeps run) runs resources in a deterministic DAG order defined by requires dependencies. You control exactly what runs and when.

Agent mode (kdeps [path]) registers whole workflows and components as tools and lets an LLM decide which to invoke in response to user prompts. Workflow tools execute as a complete pipeline so all requires: dependencies resolve. Component tools run a single reusable component in isolation. Point at a single file or a folder - folder mode exposes every workflow and agency found recursively, plus all their components.

Use workflow mode when you know the pipeline upfront. Use agent mode when you want an interactive, conversational interface.

Do I need to know go to use kdeps? ​

No. Workflows are written in YAML. The only code you might write is inline Python scripts or shell commands in python/exec resources.

What LLM providers are supported? ​

Any provider compatible with the OpenAI API format. This includes:

  • llamafile (local, the default - models run as self-contained binaries, no server install)
  • Ollama (local, opt-in)
  • OpenAI
  • Anthropic
  • Groq
  • Any custom endpoint that speaks the OpenAI chat completions protocol

Set the backend, base URL, and model via flags or environment variables.

Can I run kdeps without an LLM? ​

Yes. Resources like agent and apiResponse (and the http_request, python, exec, sql, git, and file components) do not require an LLM. You can build pure data pipelines with no AI at all.

How is this different from writing a Python script? ​

kdeps separates orchestration (the DAG, dependencies, error handling) from implementation (the actual LLM calls, HTTP requests, SQL queries). The orchestration layer handles:

  • Dependency resolution and execution order
  • Concurrent execution of independent resources
  • Error propagation and retry
  • Session and memory management
  • Input validation

You would have to write all of that yourself in a script. kdeps gives it to you from a YAML file.

How is this different from LangChain? ​

LangChain is a Python/JS library. kdeps is a standalone binary configured in YAML.

  • LangChain: you write code that calls library functions
  • kdeps: you write YAML that the engine executes

kdeps has no code dependency - install the binary, write a YAML file, and run.

Can I call one workflow from another? ​

Yes, via agencies. Use the agent: action type to call another agent's full pipeline. The caller passes params:; the callee reads them with get('key') and returns its apiResponse.response.

Can I deploy kdeps as an API server? ​

Yes. kdeps run workflow.yaml starts the HTTP API in workflow mode. kdeps ./my-agent/ starts the interactive REPL in agent mode - it is not an HTTP server. See Web server mode.

For production, use the Docker or Kubernetes deployment options.

How do I handle secrets and API keys? ​

Use environment variables. Reference them in your workflow with get('SECRET_NAME', 'env'):

yaml
# resources/example.yaml
component:
  name: http_request
  with:
    url: https://api.example.com
    headers:
      Authorization: "Bearer {{ get('API_KEY', 'env') }}"

Never hardcode secrets in workflow YAML files.

What is the maximum workflow size? ​

There is no hard limit. The engine builds an in-memory dependency graph - workflows with thousands of resources will use more memory but should work. The practical limit is readability of the YAML.

Can I use kdeps in CI/CD pipelines? ​

Yes. The kdeps run command is designed for one-shot execution. Pipe input via stdin, pass data via environment variables, and capture stdout. See the Stateless bot example.

Does kdeps support streaming? ​

Yes. Set streaming: true on a chat: resource to stream LLM responses token-by-token. This works in both workflow mode and agent mode.

Where does kdeps store session data? ​

HTTP session data (set(..., 'session')) lives in SQLite or in-memory storage, configured in settings.session. See Session configuration.

Agent mode conversation history is a different store: JSONL files under ~/.kdeps/sessions/, resumed with --resume. See Agent loop REPL features.

Does kdeps write into my project folder? ​

No. Everything kdeps generates lives under ~/.kdeps, so nothing it writes can end up in a project's git history. A project folder only holds files you write yourself.

DataWhere
Agent chat history~/.kdeps/sessions/<folder>/
Agent memory<vault>/projects/<project>/memory/ (markdown notes; default vault ~/.kdeps/notes)
Knowledge graph, caches, report<vault>/.index/
search_local index and graph~/.kdeps/projects/<folder name>-<hash>/index.db, graph.db
HTTP sessions (settings.session)~/.kdeps/sessions.db unless you set path
Models, config, API keys, connections~/.kdeps/models/, ~/.kdeps/config.yaml

kdeps only reads files you write yourself: KDEPS.md (or AGENTS.md, CLAUDE.md, ...), a .kdeps/ folder of Markdown instructions, skills and prompt templates, workflow files, and .env for the desktop Run tab. It never writes into a project's .kdeps/, so that folder is safe to commit.

bash
export KDEPS_DATA_DIR=/fast-disk/kdeps-projects   # moves ~/.kdeps/projects (index and graph dbs) elsewhere

See also ​

Released under the Apache 2.0 License.

Copyright (c) 2024-present kdeps contributors