Quickstart

Build a working LLM API in under five minutes.

Prerequisites

Install kdeps:

# macOS / Linux
curl -LsSf https://raw.githubusercontent.com/kdeps/kdeps/main/install.sh | sh

No LLM server needed: models run as local llamafiles (the default file backend). The default model (llama3.2:1b, ~1.1 GB) is downloaded to ~/.kdeps/models/ automatically on first run.

Create a project

kdeps new my-agent
cd my-agent

Or create the structure manually:

mkdir -p my-agent/resources && cd my-agent

Define your workflow

workflow.yaml:

# workflow.yaml
apiVersion: kdeps.io/v1
kind: Workflow

metadata:
  name: my-agent
  version: "1.0.0"
  targetActionId: response

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

Add an LLM resource

resources/llm.yaml:

# resources/llm.yaml
actionId: llm
name: LLM Chat
validations:
  methods: [POST]
  routes: [/api/v1/chat]
  check:
    - get('q') != ''
  error:
    code: 400
    message: "'q' is required"
chat:
  model: llama3.2:1b
  role: user
  prompt: "{{ get('q') }}"
  timeout: 60s

Add a response resource

resources/response.yaml:

# resources/response.yaml
actionId: response
name: API Response
requires: [llm]
apiResponse:
  success: true
  response:
    # chat output is the raw response object; the reply text is at .message.content
    answer: get('llm').message.content

Run it

When apiServer is configured, kdeps requires an API auth token before it starts. Set one for local development (never in workflow.yaml):

export KDEPS_API_AUTH_TOKEN=dev-token
kdeps run workflow.yaml

You can also set api_auth_token in ~/.kdeps/config.yaml. See Security Reference.

Test the API:

curl -X POST http://localhost:16395/api/v1/chat \
  -H "Authorization: Bearer $KDEPS_API_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"q": "What is entropy?"}'

Expected response:

{
  "success": true,
  "response": {
    "answer": "Entropy is a measure of disorder..."
  }
}

How it works

requires: [llm] means response will not run until llm has finished. This two-resource DAG is the simplest workflow mode pipeline.

Try agent mode

Run the workflow as a tool in an interactive LLM loop. The tool name is my-agent (from metadata.name). The LLM calls my-agent, the full pipeline executes, and the result comes back.

# Serve the current project directory -- registers one tool named "my-agent"
kdeps serve .

# Point at a folder to expose every workflow inside as separate tools
kdeps serve ./agents/

The agent REPL starts. Type a prompt and the LLM calls your workflow tools as needed.

See Also

• Modes - Understand workflow and agent modes
• Workflow Configuration - Full workflow.yaml reference
• Resources Overview - All resource types
• CLI Reference - All commands and flags