AI Agent

import { Aside } from ‘@astrojs/starlight/components’;

The AI Agent is the core of Kodel.AI — a sandboxed process that receives tasks, uses an LLM to reason about them, and executes code in a Docker container.

Agent lifecycle

task.assigned
     │
     ▼
┌─────────────────────────────┐
│  loop:                      │
│    llm.request →            │
│      ← llm.response.done    │
│    parse tool_calls         │
│    execute tools            │
│    step.report →            │
└─────────────────────────────┘
     │
     ▼
task.complete / task.error

Available tools

The agent has 6 built-in tools it can call during task execution:

Tool	Description
read_file	Read file contents from /workspace
write_file	Create or overwrite a file
edit_file	Make targeted edits with search/replace
bash	Run shell commands (tests, git, npm, etc.)
glob	Find files by pattern
grep	Search file contents with regex

All file paths are resolved relative to `/workspace` (configurable via `WORKSPACE_DIR`). The agent cannot access files outside this directory.

LLM integration

The agent doesn’t call the LLM directly — it sends llm.request messages to the server over WebSocket. The server proxies the request to your configured LLM provider and streams chunks back as llm.response.chunk messages.

This design means:

• The LLM API key never touches the agent container
• You can switch LLM providers without redeploying agents
• The server can log, rate-limit, and monitor all LLM calls

System prompt

The agent’s behavior is controlled by a system prompt in packages/server/src/system-prompt.ts. You can override it per-deployment via the SYSTEM_PROMPT environment variable.

Sandbox security

Each agent runs in an isolated Docker container with:

• No network access by default (configurable)
• Workspace limited to /workspace
• Resource limits (CPU, memory) via Docker

For tasks requiring Docker-in-Docker (building images, running containers), enable the dind option in the Instance Template — this uses the Sysbox runtime for secure nested containerization.