AI Appliances: Build & Deploy Autonomous AI Agents and Agencies in YAML
- About This Book
- How This Book Is Organized
- Code Conventions
Chapter 1: Why AI Appliances?
- The Prototype Problem
- The AI Appliance Model
- What Makes Production AI Hard
- Two Modes, One Workflow File
- Who Is kdeps For?
- No Lock-In, By Design
- Built to Last
- If You Are Coming From Another Framework
- What You Will Build in This Book
Chapter 2: Getting Started
- Installing kdeps
- The Local LLM Comes Built In
- Creating Your First Project
- The Workflow Entry Point
- Adding an LLM Resource
- Adding a Response Resource
- Running the Workflow
- How the Execution Flows
- Hot Reload for Development
- What You Just Built
Chapter 3: Core Concepts
- Resources: The Unit of Work
- The DAG: Dependency-Ordered Execution
- The Data Store: get() and set()
- Workflow Mode vs. Agent Mode
- Backends: Separating Model from Execution
- Expressions: The Glue
- Putting It Together
Chapter 4: Workflow Mode
-
Starting a Workflow
-
Request Lifecycle
-
Declaring Dependencies with
requires: -
Parallel Execution
-
Validation
-
The before: and after: Blocks
-
Designing Effective DAGs
-
A Real-World Example: Document Q&A Pipeline
-
Multiple Routes on One Workflow
-
What Workflow Mode Is Not
Chapter 5: Agent Mode
- Starting Agent Mode
- What the LLM Sees
- Single Workflow vs. Folder Mode
- Tool Inputs and Outputs
- A Practical Example: Research Assistant
- Tool Names Matter
- Built-In Agent Tools
- Agent Registries (In-Memory)
- Approval Tokens
- REPL Slash Commands
- Skills
- Session Persistence
- Mixing Modes: The Two-Layer Architecture
- Limitations and Trade-offs
- Next Steps
Chapter 6: LLM Resources
- Basic Usage
- Full Configuration Reference
- Structured JSON Output
- System Prompts
- Multi-Turn Conversations
- tools: — Function Calling (Resource-Based Tools)
- componentTools: — Component-Based Tools
- Timeouts
- Configuring Backends
- Environment Variables in Config
- Sampling Parameters
- Vision (Multimodal Input)
- Model Routing
- Streaming (Ollama)
- Chain-of-Thought and Few-Shot Selection
- Provider-Specific Options
- Choosing the Right Model
- The Output
Chapter 7: Data Resources
- SQL Resource
- HTTP Client Resource
- Python Resource
- Exec Resource
- Combining Data Resources
- Email Resource
Chapter 8: Knowledge Resources
- Scraper Resource
- Search Resources
- Embedding Resource
Chapter 9: Browser Automation
- Why a Real Browser
- Basic Usage
- Browser Engines
- Actions
- Authentication: Logging In
- Session Persistence
- Full Example: Extracting a Dynamic Dashboard
- Headless vs. Headed Mode
- Performance Considerations
- When to Use Browser vs. Scraper vs. httpClient
Chapter 10: API Response and Validation
- The API Response Resource
- Validations
- The onError Block
- Practical: A Complete API with Proper Validation
Chapter 11: Expressions and Data Flow
- Two Syntaxes
- The Data Store Functions
- Standard Library
- Helper Functions
- before: and after: Patterns
- Practical: Data Pipeline with Expressions
- The input Object Shorthand
- Inline Resources in before: and after:
- Jinja2 YAML Preprocessing
- Common Mistakes
Chapter 12: Components
- Why Components
- Registry Components
- Components as LLM Tools
- Custom Components
- Design Principles for Components
- The Component Registry at kdeps.io
- Publishing to the Registry
Chapter 13: Agencies — Multi-Agent Systems
- Why Agencies
- Directory Structure
- The Agency Manifest
- Calling One Agent from Another
- A Complete Multi-Agent Example
- Running the Agency
- Packed Agent Archives
- Packaging the Entire Agency (.kagency)
- Independent Deployment
- Agency Design Principles
Chapter 14: Workflow Configuration
- Top-Level Structure
- metadata
- apiServer
- agentSettings
- sqlConnections
- A Production-Ready workflow.yaml
- Environment Variable Best Practices
Chapter 15: Sessions, CORS, and Route Restrictions
-
Sessions
-
Persistent Memory
-
CORS
-
Route and Method Restrictions
-
Putting It Together: A Stateful API
Chapter 16: Advanced Configuration
- Persistent Memory Configuration
- Rate Limiting
- Trusted Proxies
- TLS
- Authentication
- Security Headers
- Body Size and Concurrency Limits
- Request Body Size Preflight
- Resource Output Caps
- The Request Object
- Health Endpoints
- Per-Agent Config Profiles
- Provider-Specific Chat Options
- Production Security Checklist
Chapter 17: Docker Deployment
- The Two-Step Build
- Packaging
- Building Docker Images
- Running the Docker Image
- Pushing to a Registry
- Environment Configuration Patterns
- Image Size Optimization
- CI/CD Integration
Chapter 18: Kubernetes Deployment
- Generating Manifests
- What Gets Generated
- Command Reference
- Adding Secrets and Config
- Persistent Storage
- Exposing the Agent
- Health Checks
- NetworkPolicy (Opt-In)
- Resource Limits
- Horizontal Pod Autoscaling
- Complete Production Setup
- Updating a Deployment
Chapter 19: Standalone Binary
- Overview
- How It Works
- Supported Architectures
- Typical Workflow
- Running the Prepackaged Binary
- Edge Device Deployment
- Embedding the Model: —include-models
- Air-Gapped Environments
- Systemd Service
- Pinning the Runtime Version
- Comparing Deployment Targets
Chapter 20: WebServer Mode
-
Why WebServer Mode
-
Basic Configuration
-
Static File Serving
-
Subprocess Proxy Mode
-
The Request Routing Logic
-
Production: Building the Frontend In
-
WebSockets
-
Development Workflow
-
Example: Full-Stack Agent with Dashboard
Chapter 21: Validate, Debug, and Develop
- kdeps validate
- kdeps doctor
- Hot-Reload Development Mode
- Debugging Resource Execution
- FAQ and Common Problems
- Logging and Observability
- The Management API
Chapter 22: Iteration — items and loop
- items: — For-Each Iteration
- loop: — While-Loop Iteration
- items vs. loop: Choosing the Right Tool
Chapter 23: Error Handling with onError
- The Default: Fail Loud
- onError: Syntax
- The Three Actions
- The error Object
- Conditional Error Handling with when:
- Practical Patterns
- Error Handling vs. Validation
### Chapter 24: Real-World Examples
- Example 1: Customer Support Bot (Multi-Turn)
- Example 2: Document Processing Pipeline
- Example 3: Autonomous Research Agency
- Example 4: Content Moderation API
- Example 5: Telegram Bot
Chapter 25: Bot and File Input Sources
- Three Input Sources
- Bot Source
- The botReply: Resource
- File Input Source
- Choosing an Input Source
Appendix A: Troubleshooting
- Resource Did Not Execute
- get() Returns null
- Validation Always Fails (or Never Fires)
- LLM Does Not See Context From a Previous Resource
- DAG Cycle Error
- Session Not Persisting Between Requests
- HTTP Request Returns 500 With No Useful Message
- Expression Evaluation Error: “undefined: X”
- Resource Runs But Output Is Empty or Wrong Shape
- kdeps validate Passes But Runtime Fails
- Deployment: Docker Image Starts But Agent Returns Errors
- Getting More Information
Appendix B: Security
- Secrets Management
- Prompt Injection
- Authentication and Authorization
- Transport Security (TLS)
- Rate Limiting for Abuse Prevention
- Input Validation as a Security Boundary
- SQL Injection
- Multi-Tenant Isolation
- Logging and Audit Trails
- Security Checklist for Production Deployments
Appendix C: Testing Your Agent
- What You Can Test Deterministically
- What Requires Human Judgment or Statistical Evaluation
- Smoke Testing With curl
- Shell-Based Integration Test Script
- Testing With
--dev
Hot Reload - Testing Validation Rules
- Testing Session Persistence
- Testing onError Paths
- Testing Agent Mode Tool Selection
- CI/CD Integration
- What Not to Test
About the Author
Resources
Quick Reference
- Key Commands
- Resource Types Summary
- Expression Quick Reference
- Deployment Comparison
source & further reading
leanpub.com — original article
The Leanpub Podcast 🎙 Feat. MaxGuernseyIII, Author of No Direction
Leanpub Book LAUNCH 🚀 Rethinking Performance Engineering for Agentic AI by Kandasamy Selvaraj
Leanpub Book LAUNCH 🚀 Architect the Agent: The CCAR-F Certification Guide by Thomas De Vos