Resources Overview

Resources are the fundamental building blocks of KDeps workflows. Each resource performs a specific action and can depend on other resources.

Resource Structure

Every resource follows this structure:

apiVersion: kdeps.io/v1
kind: Resource

metadata:
  actionId: myResource        # Unique identifier
  name: My Resource           # Human-readable name
  description: What it does   # Optional description
  category: api               # Optional: for organization
  requires:                   # Dependencies
    - otherResource

items:                        # Optional: for iteration
  - item1
  - item2

run:
  # Request restrictions and validation
  validations:
    methods: [POST]
    routes: [/api/v1/endpoint]
    headers: [Authorization]
    params: [q, limit]
    skip:
    - get('skip') == true
    check:
      - get('q') != ''
    error:
      code: 400
      message: Query required

  # Processing expressions
  exprBefore:                 # Runs BEFORE the main action
    - set('pre', 'value')
  expr:                       # Runs AFTER the main action (default)
    - set('post', 'value')
  exprAfter:                  # Alias for expr
    - set('also_post', 'value')

  # Action (only one per resource)
  chat: { ... }        # LLM chat
  httpClient: { ... }  # HTTP request
  sql: { ... }         # Database query
  python: { ... }      # Python script
  exec: { ... }        # Shell command
  scraper: { ... }     # Content scraping
  tts: { ... }         # Text-to-Speech
  pdf: { ... }         # PDF generation
  calendar: { ... }    # ICS calendar file
  search: { ... }      # Web or local filesystem search
  botReply: { ... }    # Bot reply
  embedding: { ... }   # Vector DB (index / search / delete)
  browser: { ... }     # Browser automation (Playwright)
  agent: { ... }       # Call another agent (agency)
  apiResponse: { ... } # API response

Resource Types

Type	Description	Use Case
chat	LLM interaction	AI responses, text generation
httpClient	HTTP requests	External APIs, webhooks
sql	Database queries	Data retrieval, updates
python	Python scripts	Data processing, ML
exec	Shell commands	System operations
scraper	Content extraction	Web pages, PDFs, documents, images
tts	Text-to-Speech synthesis	Voice output, audio responses
pdf	PDF generation	Reports, letters, tailored documents
calendar	ICS calendar read/write	Schedule management, event creation
search	Web or local filesystem search	Content discovery, research pipelines
botReply	Chat bot reply	Discord, Slack, Telegram, WhatsApp
embedding	Vector embeddings & search	RAG pipelines, semantic search
browser	Browser automation	Web scraping, form filling, screenshots
agent	Inter-agent delegation	Multi-agent agencies
apiResponse	Response formatting	Final output

Metadata

actionId (Required)

Unique identifier for the resource. Used to reference output from other resources.

metadata:
  actionId: llmResource

# Access output in another resource:
data: get('llmResource')

description (Optional)

Human-readable description of what the resource does.

metadata:
  actionId: llmResource
  name: LLM Chat
  description: Processes user queries using language models

category (Optional)

Organize resources by category for better management.

metadata:
  actionId: userAuth
  name: User Authentication
  category: auth

metadata:
  actionId: dataProcessor
  name: Data Processor
  category: processing

Common categories: api, auth, processing, storage, ai, utils.

requires (Dependencies)

List of resources that must execute before this one.

metadata:
  actionId: responseResource
  requires:
    - llmResource
    - httpResource

KDeps automatically builds a dependency graph and executes resources in the correct order.

Request Restrictions

validations.methods

Limit which HTTP methods trigger this resource:

run:
  validations:
    methods: [GET, POST]

validations.routes

Limit which routes trigger this resource:

run:
  validations:
    routes: [/api/v1/chat, /api/v1/query]

validations.headers / validations.params

Whitelist specific headers or parameters:

run:
  validations:
    headers:
      - Authorization
      - X-API-Key
    params:
      - q
      - limit
      - offset

Validation

validations.skip

Skip resource execution based on conditions:

run:
  validations:
    skip:
      - get('skip') == true
      - get('mode') == 'fast'

If any condition evaluates to true, the resource is skipped.

validations.check

Validate inputs before execution:

run:
  validations:
    check:
      - get('q') != ''
      - get('limit') <= 100
    error:
      code: 400
      message: Invalid request parameters

If validation fails, the error response is returned immediately.

Processing with Expressions

Execute logic before or after the main action:

exprBefore

Runs before the main action. Use this to prepare data used in the resource's own configuration (like prompts or URLs).

run:
  exprBefore:
    - set('full_name', get('first') + ' ' + get('last'))
  chat:
    prompt: "Hello {{ get('full_name') }}"

expr (or exprAfter)

Runs after the main action. Use this to process results or update state for subsequent resources.

run:
  chat:
    prompt: "Summary of {{ get('q') }}"
  expr:
    - set('summary', get('myResourceId'))
    - set('processed_at', info('timestamp'))

See Expressions for detailed documentation.

Items Iteration

Process multiple items in sequence:

items:
  - "First item"
  - "Second item"
  - "Third item"

run:
  chat:
    prompt: "Process: {{ get('current') }}"

Access iteration context:

• get('current') - Current item
• get('prev') - Previous item
• get('next') - Next item
• get('index') - Current index (0-based)
• get('count') - Total item count

Loop Iteration

Repeat a resource body while a condition is true (Turing-complete while-loop). Add every: to pause between iterations for a ticker pattern, or at: to fire at specific dates/times:

run:
  loop:
    while: "loop.index() < 5"
    maxIterations: 1000   # safety cap (default: 1000)
    every: "1s"           # optional: wait 1 second between iterations
  expr:
    - "{{ set('result', loop.count()) }}"
  apiResponse:
    success: true
    response:
      count: "{{ get('result') }}"

Access loop context:

• loop.index() - Current index (0-based)
• loop.count() - Current count (1-based)
• loop.results() - Results from all prior iterations

Loop fields:

• while - Boolean expression; loop runs while truthy
• maxIterations - Safety cap (default: 1000)
• every - Optional inter-iteration delay ("500ms", "1s", "2m", "1h"). Mutually exclusive with at
• at - Optional array of specific dates/times (RFC3339, "HH:MM", or "YYYY-MM-DD"). Mutually exclusive with every

When apiResponse is present, each iteration produces one streaming response map.

Resource Output

Each resource produces output that can be accessed by dependent resources:

# LLM resource output
metadata:
  actionId: llmResource
run:
  chat:
    model: llama3.2:1b
    prompt: "Answer: {{ get('q') }}"

# Access in another resource
metadata:
  requires: [llmResource]
run:
  apiResponse:
    response:
      answer: get('llmResource')  # Get the LLM response

Execution Flow

Request
    ↓
┌─────────────────┐
│ Route Matching  │
└────────┬────────┘
         ↓
┌─────────────────┐
│ Build Dep Graph │
└────────┬────────┘
         ↓
For each resource (in order):
    ┌─────────────────┐
    │ Check Route     │ → Skip if not matching
    └────────┬────────┘
             ↓
    ┌─────────────────┐
    │ Check Skip      │ → Skip if condition true
    └────────┬────────┘
             ↓
    ┌─────────────────┐
    │ Preflight Check │ → Error if validation fails
    └────────┬────────┘
             ↓
    ┌─────────────────┐
    │ Execute exprBefore │
    └────────┬────────┘
             ↓
    ┌─────────────────┐
    │ Execute Action  │
    └────────┬────────┘
             ↓
    ┌─────────────────┐
    │ Execute expr    │
    └────────┬────────┘
             ↓
    ┌─────────────────┐
    │ Store Output    │
    └─────────────────┘
         ↓
┌─────────────────┐
│ Return Target   │
└─────────────────┘

Best Practices

1. Use Descriptive actionIds

# Good
actionId: fetchUserProfile
actionId: validatePayment

# Avoid
actionId: resource1
actionId: r2

2. Single Responsibility

Each resource should do one thing well. Split complex logic into multiple resources.

3. Validate Early

Use validations.check to validate inputs before expensive operations.

4. Handle Dependencies

Only list direct dependencies in requires. KDeps handles transitive dependencies.

5. Use Appropriate Timeouts

Set realistic timeoutDuration values based on expected execution time.

Next Steps

• LLM Resource - AI model integration
• HTTP Client - External API calls
• SQL Resource - Database operations
• Python Resource - Script execution
• Exec Resource - Shell commands
• Scraper Resource - Content extraction
• TTS Resource - Text-to-Speech synthesis
• PDF Resource - PDF generation from HTML or Markdown
• Calendar Resource - ICS calendar read/write
• Search Resource - Web and local filesystem search
• Browser Automation - Playwright-based web browser control
• Embedding Resource - Vector DB & semantic search
• API Response - Response formatting
• Agency & Multi-Agent - Multi-agent orchestration