Build AI agents for the Codebolt platform using @codebolt/agent. Use when creating agents, configuring the agent loop, writing custom message modifiers, implementing processors, creating tools, building workflows, ActionBlocks, or choosing between abstraction levels. Covers Remix Agents (no-code), Level 1 (direct APIs), Level 2 (base components), Level 3 (high-level CodeboltAgent), and ActionBlocks for reusable logic.
SDK Version 2 - This documentation covers Codebolt SDK v2.
⚠️ IMPORTANT: Do NOT use
codebolt.waitForConnection()In SDK v2,
waitForConnection()has been removed. Connection handling is now automatically managed insidecodebolt.onMessage(). If you're migrating from v1 or see old examples usingwaitForConnection(), simply remove those calls.// ❌ OLD (SDK v1) - Do NOT use await codebolt.waitForConnection(); codebolt.onMessage(async (msg:FlatUserMessage) => { ... }); // ✅ NEW (SDK v2) - Use this codebolt.onMessage(async (msg:FlatUserMessage) => { ... });
⚠️ IMPORTANT: Use Strict Typings & Always Check for Errors
Always use strict TypeScript typings when developing agents. You do NOT need to create custom typings — types for most Codebolt functionality are already provided by the packages (@codebolt/codeboltjs, @codebolt/agent, @codebolt/types). Just use the existing types.
After writing any agent code, always run type checking and linting to catch errors before running the agent.
# Always run after writing code
npx tsc --noEmit # Check for type errors
npx eslint src/ # Check for code quality issues
Use the codebolt-cli command-line tool to generate templates for agents and MCP tools. This is the recommended starting point for creating new agents or tools.
# Interactive mode (recommended)
npx codebolt-cli createagent
# Quick mode with name
npx codebolt-cli createagent -n "MyAgent" --quick
This generates a complete agent project structure with:
codeboltagent.yaml - Agent configurationpackage.json - Dependenciessrc/index.ts - Entry point with boilerplate code# Interactive mode
npx codebolt-cli createtool
# With options
npx codebolt-cli createtool -n "MyTool" -i "my-tool-id" -d "Tool description"
This generates an MCP tool project with:
codebolttool.yaml - Tool configurationpackage.json - Dependenciessrc/index.ts - MCP server boilerplate| Command | Description |
|---|---|
npx codebolt-cli login | Authenticate with Codebolt platform |
npx codebolt-cli publishagent [path] | Publish agent to registry |
npx codebolt-cli publishtool [path] | Publish MCP tool to registry |
npx codebolt-cli listagents | List your published agents |
npx codebolt-cli listtools | List your published MCP tools |
npx codebolt-cli startagent [path] | Start agent locally for testing |
npx codebolt-cli cloneagent <id> [path] | Clone an existing agent |
npx codebolt-cli inspecttool <file> | Debug tool with MCP inspector |
my-agent/
├── codeboltagent.yaml # Agent configuration (required)
├── package.json # Dependencies
├── src/
│ └── index.ts # Agent entry point
└── dist/ # Compiled output
Codebolt provides a 4-tier architecture for building AI agents:
┌─────────────────────────────────────────────────────────────────┐
│ REMIX AGENTS: No-Code Configuration │
│ Markdown files with YAML frontmatter + custom instructions │
│ → Use when: You want agents without writing any code │
├─────────────────────────────────────────────────────────────────┤
│ LEVEL 3: High-Level Abstractions │
│ CodeboltAgent, Agent, Workflow, Tools │
│ → Use when: You want a ready-to-use agent with minimal setup │
├─────────────────────────────────────────────────────────────────┤
│ LEVEL 2: Base Components │
│ InitialPromptGenerator, AgentStep, ResponseExecutor │
│ → Use when: You need control over the agent loop │
├─────────────────────────────────────────────────────────────────┤
│ LEVEL 1: Direct APIs │
│ codebolt.llm, codebolt.fs, codebolt.terminal, etc. │
│ → Use when: You want to build everything from scratch │
└─────────────────────────────────────────────────────────────────┘
↑↓ Mix & Match ↑↓
┌─────────────────────────────────────────────────────────────────┐
│ ActionBlocks: Reusable logic units invoked from any level │
└─────────────────────────────────────────────────────────────────┘
Remix Agents let you create agents without writing any code. They're stored as markdown files with YAML frontmatter in .codebolt/agents/remix/.
---