Skip to content

Examples ​

Complete, runnable projects. Copy the files on the page and run the command there. A local model needs no API key. Add a key only when that example calls a cloud provider.

The examples are in groups. Pick the one closest to what you are building.

Workflow file ​

ExampleWhat it demonstrates
Document summarizerThe file input source - read one file, return JSON, exit
Batch processingitems: iteration - process a list in one request
Document search (RAG)component: embedding upsert and search, two routes in one workflow
Login and sessionsSQLite sessions, set/get session scope, auth gate
Shell command APIthe exec component with a timeout, method scoping, info()
Function callingLLM tools:, script:, tool arguments in memory
Image analysisMultipart upload, files: on a chat prompt, Ollama vision
SQL-backed APIsql component: parameterized queries, CSV output, batch transactions
Chat web appAPI + static frontend together, public routes, scenario:
File uploadMultipart uploads, info('files'), get(field, 'filepath')
Design review panelParallel reviewers, a question in the reply, the answer in the next request (session)
Conditionals and listsTernary, &&/`
Authenticated API callcomponent: http_request bearer/API-key auth, retry:, cache:
MCP server toolsLLM tools backed by an external MCP server
Inline resourcesFull actions inside before: / after:
Local file searchcomponent: search_local glob + content search
Python data processingpython component, input(), packages:, JSON output
Static siteWeb server mode, static file serving
Stateless botOne-shot stdin/stdout LLM calls - cron jobs, CI pipelines
Telegram botPolling loop, multi-resource pipelines, external API calls
ShowcaseComplex agents in ~20 lines of YAML - multiple real-world patterns

Agencies ​

ExampleWhat it demonstrates
Two-agent agencykind: Agency, agent: resource, params:
Reusable componentcomponent.yaml, interface.inputs, component: + with:
Per-component env varsenv() scoping, {COMPONENT}_{VAR} override, .env files

Document summarizer ​

A single-shot workflow that reads a document from --file, stdin, or an environment variable. It sends the document to a local LLM and prints a structured JSON summary. It runs one time and stops.

Best for:

  • Cron jobs and CI steps
  • kdeps run ... | jq one-liners
  • Any pipeline that treats kdeps as a subprocess

Build it step by step

Batch processing ​

An API that takes a list of items in one request. It makes one HTTP call for each item with items:, transforms each result, and returns an aggregated summary.

Best for:

  • Enriching a list of records from an external API
  • Running the same LLM prompt over many inputs
  • Any fan-out / collect pattern

Build it step by step

Document search (RAG) ​

A two-route API: POST /index stores a document, POST /search returns the closest matches. Uses the built-in embedding component - a local SQLite index, no vector database.

Best for:

  • The retrieval half of a RAG pipeline
  • A lightweight search endpoint over your own text
  • Learning validations.routes scoping

Build it step by step

Login and sessions ​

An API with a POST /login endpoint that starts a SQLite-backed session and a GET /session endpoint that only works for a logged-in caller.

Best for:

  • Adding authentication to a workflow
  • Learning session storage scopes

Build it step by step

Shell command API ​

An endpoint that runs a shell command with the exec component and returns its output. Use this pattern to give a script or CLI tool as an HTTP service.

Best for:

  • Wrapping an existing script
  • System checks and automation endpoints

Build it step by step

Function calling ​

An API where the LLM calls your own resources mid-response - a python component calculator and a mock database lookup - then answers using the results.

Best for:

  • Let a model calculate or look up data, so that it does not guess
  • Learning the tools: / script: pattern

Build it step by step

Image analysis ​

An API that accepts an image upload and a question, sends both to a multimodal model, and returns a structured description.

Best for:

  • Vision use cases (captioning, object listing, scene classification)
  • Learning file uploads and files: on a chat prompt

Build it step by step

SQL-backed API ​

A two-route API over SQLite: GET /report runs an analytics query and returns CSV. POST /update applies a batch of writes in a transaction.

Best for:

  • Exposing a database read or write as an HTTP endpoint
  • Learning parameterized queries and paramsBatch:

Build it step by step

Chat web app ​

One project that serves a chat API and the static web page that calls it. The API route is public so the browser needs no token. The LLM has a system prompt from scenario: and a friendly onError fallback.

Best for:

  • A complete, deployable chat UI in one repo
  • Learning apiServer: + webServer: together

Build it step by step

File upload ​

An endpoint that accepts one or more multipart uploads and returns their metadata - count, names, MIME types, and the first file's path on disk.

Best for:

  • Accepting user files
  • The first step of any upload-then-process pipeline

Build it step by step

Conditionals and lists ​

One resource that exercises every expression control-flow tool: the ternary operator, && / || / !, and filter / map / all / any over a list.

Best for:

  • A reference for expression syntax you can run and poke at

Build it step by step

Authenticated API call ​

An endpoint that calls a third-party API with a bearer token. It tries again only on 5xx, with exponential backoff. It keeps the response in a cache for five minutes. The connectionName, retry:, and cache: inputs of the http_request component do all of this.

Best for:

  • Wrapping a paid or rate-limited upstream API
  • Learning the built-in retry and cache options

Build it step by step

MCP server tools ​

Give an LLM tools backed by an external Model Context Protocol server. kdeps starts the server as a subprocess, calls the tool, and shuts it down.

Best for:

  • Reusing the growing ecosystem of MCP servers
  • Sandboxed filesystem or API access for a model

Build it step by step

Inline resources ​

Attach component: and chat: actions directly to one resource's before: and after: blocks. You do not make a file for each.

Best for:

  • One-off setup and teardown a single resource needs
  • Keeping a small workflow in one file

Build it step by step

Search a directory by filename pattern and content keyword with the search_local component.

Best for:

  • A search endpoint over files on disk
  • The non-semantic counterpart to the RAG tutorial

Build it step by step

Python data processing ​

An API that runs a Python script to validate and convert data formats. Shows how a python component receives request fields and returns structured data.

Best for:

  • Anything with no native resource - parsing, transforms, calculations
  • Learning input() templating and packages:

Build it step by step

Static site ​

Serve a folder of HTML, CSS, and JS over HTTP with web server mode. No resources, no LLM.

Best for:

  • A frontend in front of an agent API
  • A docs site or dashboard

Build it step by step

Stateless bot ​

A one-shot bot that reads from stdin (or an env var), calls an LLM, and writes the reply to stdout. No server, no polling, no state.

Best for:

  • Cron jobs that summarize data
  • CI pipeline steps that classify or label
  • Custom integrations that call kdeps as a subprocess
bash
echo "What is 2+2?" | kdeps run workflow.yaml

Telegram bot ​

A polling bot that watches for Telegram messages and replies with LLM responses. Two resources chained together: llm calls the model, reply returns the answer, and kdeps sends it back through the Telegram API.

Best for:

  • Chatbot interfaces over existing workflow resources
  • Notification-driven pipelines
  • Multi-resource orchestration patterns
bash
TELEGRAM_BOT_TOKEN=... kdeps run workflow.yaml

Showcase ​

A collection of real-world agents. Each agent is a complete workflow. Send a POST to it, and you get structured JSON. Covers data extraction, classification, summarization, and more.

Best for:

  • Seeing how complex agents fit in ~20 lines of YAML
  • Learning the POST /api/v1/run pattern
  • Adapting a pattern to your own data

Two-agent agency ​

Two agents in one project: the entry-point agent calls the other with the agent: resource and returns the combined result. Introduces kind: Agency and the agency.yaml manifest.

Best for:

  • Splitting a large workflow into independently testable agents
  • Learning multi-agent orchestration

Build it step by step

Reusable component ​

Build a component - a bundle of resources with a typed input interface - and call it from a workflow with component:.

Best for:

  • Packaging logic you reuse across projects
  • Learning the interface.inputs schema and auto-discovery

Build it step by step

Per-component env vars ​

Two components that read the same variable name. Each can have a different value with a {COMPONENT}_{VAR} prefix. The example also shows the .env file that kdeps makes for each component.

Best for:

  • Give each component its own API key, with no change to shared YAML
  • Understanding component env resolution order

Build it step by step

See also ​

kdeps has the Apache 2.0 License.