Input sources

A workflow is fed by an HTTP server (settings.apiServer), a chat bot, or one file. The bot and file feeds are named under settings.input.

This controls how a running workflow is fed. Agent mode does not use these sources; the prompt is stdin in the REPL. When the LLM calls a workflow as a tool, that workflow still uses its own input settings.

Overview

Source	Use Case
api	Valid source name. Does not open a port.
bot	Chat bot platforms (Discord, Slack, Telegram)
file	File content from stdin, env var, or configured path (single-shot)

An HTTP server starts only when settings.apiServer is set. Leave portNum out and it listens on port 16395. Omitting settings.input does not start that server. With no apiServer, no webServer, no bot source, and no file source, kdeps run executes the workflow once and exits.

API source

settings.apiServer starts the HTTP server. sources: [api] does not.

# workflow.yaml
settings:
  apiServer:
    hostIp: "127.0.0.1"
    portNum: 16395
    routes:
      - path: /api/v1/chat
        methods: [POST]

Requests are JSON and routed to resources based on metadata.targetActionId in the workflow.

Use validations.methods and validations.routes in individual resources to scope them to specific routes.

Bot source

The bot source connects to chat platforms. Supported platforms: Discord, Slack, Telegram. WhatsApp has no long-lived connection - Meta calls a webhook - so a WhatsApp bot is an ordinary API workflow: kdeps new my-bot --template whatsapp-bot.

Bot credentials belong in ~/.kdeps/config.yaml, not workflow.yaml. The workflow only declares which platforms to enable.

# ~/.kdeps/config.yaml
bot_connections:
  discord:
    botToken: "${DISCORD_BOT_TOKEN}"
  slack:
    botToken: "${SLACK_BOT_TOKEN}"
    appToken: "${SLACK_APP_TOKEN}"

# workflow.yaml
settings:
  input:
    sources: [bot]
    bot:
      executionType: polling
      discord: {}   # presence enables the platform; credentials are in ~/.kdeps/config.yaml
      slack: {}

Execution types:

• polling (default): Long-running persistent connection. Blocks until SIGINT/SIGTERM.
• stateless: Reads one message from stdin as JSON, executes the workflow once, writes the result (the reply) to stdout, then exits.

File source

The file source reads file content from stdin, the KDEPS_FILE_PATH environment variable, or a configured path. The workflow executes once and exits.

# workflow.yaml
settings:
  input:
    sources: [file]
    file:
      path: /data/input.txt

Override the path at runtime:

kdeps run workflow.yaml --file /path/to/document.txt

The workflow runs once and prints its result (the target resource's output) as JSON on stdout, after the progress lines:

✓ Running workflow with file input...
{
  "data": {
    "summary": "..."
  },
  "success": true
}

Size limit. The whole file is read into memory as fileContent - fine for documents, but a workflow that ingests bulk data (a large CSV, say) can spike memory well past the raw file size once a resource copies that content again (e.g. interpolating it into a python component script or exec component argument, or a script that builds an in-memory row list). Past a certain size that risks an OOM kill from the OS - which, being a SIGKILL, leaves no error and no core dump, just a vanished process. --file/stdin input is capped at 256 MiB by default; kdeps run fails fast with a clear error instead of reading a file over that. Raise or lower it with KDEPS_FILE_INPUT_MAX_BYTES (bytes; 0 disables the check):

KDEPS_FILE_INPUT_MAX_BYTES=1073741824 kdeps run workflow.yaml --file big-export.csv  # 1 GiB

If you hit this limit often, prefer having the workflow process the file in batches (e.g. a python component or exec component step that streams rows) over one step that holds the whole dataset in memory - the limit is a safety net, not a size to build up to.

Interactive REPL

Start an interactive LLM REPL alongside the normal workflow execution with the --interactive flag. This is independent of the configured input source:

kdeps run workflow.yaml --interactive

This opens a terminal REPL where you can send prompts and invoke tools interactively.

Use cases

• Serve a workflow as an HTTP JSON API for a frontend or another service (settings.apiServer).
• Run a workflow as a chat bot on Discord, Slack or Telegram (WhatsApp: the whatsapp-bot template) (bot).
• Process one file per invocation from a pipeline, cron job, or CI step (file).

See also

• Workflow configuration - full settings reference
• Workflow mode - how the request-response cycle works
• Bot configuration - full bot settings