kdeps workflow

A deterministic YAML pipeline. A request arrives, resources execute in dependency order, the result is returned - same input, same execution path, every time. Auditable, testable, safe to run unattended. Serve it as an HTTP API, a bot, or a file processor.

kdeps run ./my-agent/      # run once / serve on :16395

Not this? For an autonomous agent that decides what to do next, use kdeps agent. To run several workflows/agents as one system, kdeps agencies. To ship this pipeline as an appliance, kdeps deploy.

---

If the workflow has no chat: resource, kdeps does not download a model or start an LLM server. /health binds immediately. Models download on the first chat request.

How it works

A resource runs only after everything in its requires: has produced output. Resources with no shared dependency path run concurrently.

When to use workflow mode

• You need a deterministic, auditable pipeline.
• You are building a REST API, bot, or file-processing service.
• You want full control over which resources run and in what order.
• You need validation, early-exit, and explicit error handling.

Comparison with agent mode

	Workflow mode (kdeps run)	Agent mode (kdeps [path])
Execution	DAG, deterministic	LLM loop, tool-driven
Entry point	metadata.targetActionId	User prompt
Unit of work	Individual resources	Whole workflows
Tools	Functions in chat.tools	One per workflow + one per component + built-ins
Input	One workflow path	Optional file or folder
Conversation	Single run	Multi-turn, persistent JSONL

Minimal example

The two-resource chat API, the auth token, and the curl are on the workflow quickstart. /health is exempt from that token. /_kdeps/* management routes use KDEPS_MANAGEMENT_TOKEN instead. See Security reference.

Input sources

Workflow mode supports three input sources configured in settings:

# API (default) - starts an HTTP server
settings:
  apiServer:
    portNum: 16395
    routes:
      - path: /api/v1/chat
        methods: [POST]

# Bot - connects to a chat platform; blocks until SIGINT
# Credentials go in ~/.kdeps/config.yaml bot_connections, not here
settings:
  input:
    sources: [bot]
    bot:
      executionType: polling   # polling = persistent; stateless = one message then exit
      discord: {}              # presence enables the platform

# File - reads one file from disk or stdin, runs once, exits
settings:
  input:
    sources: [file]
    file:
      path: /data/input.txt

See Input sources for full configuration.

Agent memory (--memory)

Workflow mode can use the same persistent memory facilities as agent mode. Pass --memory to enable:

kdeps run workflow.yaml --memory
kdeps exec my-agent --memory

When enabled, four expression functions become available in resource YAML:

Function	Description
memory_save(key, value)	Save a key-value pair to persistent memory
memory_search(query)	Search memory entries by content (returns JSON array)
memory_list()	List all memory keys
memory_delete(key)	Delete a memory entry by key

Memory persists across workflow runs as notes in the knowledge vault's Memory/ folder (default ~/.kdeps/notes/Memory/). Use it to carry state between invocations:

# resources/llm.yaml
actionId: llm
before:
  - memory_save('last_query', get('q'))
chat:
  model: llama3.2:1b
  prompt: |
    Previous context: {{ memory_search('user preference') }}
    Answer: {{ get('q') }}

# resources/response.yaml
actionId: response
requires: [llm]
before:
  - memory_save('last_response', get('llm').message.content)
apiResponse:
  success: true
  response:
    answer: get('llm').message.content

Memory entries are automatically linked into a relationship graph showing the chain from prompt to tool calls to results.

See also

• Workflow configuration - Full workflow.yaml reference
• Resources overview - Resource types and fields
• Agent mode - Autonomous LLM loop