Skip to main content

Creating Agents

This subsection is about authoring agents. If you want an AI specialised for your codebase, your domain, your coding conventions — this is where you build it.

For extending existing agents without writing a new one, see Agent Extensions.

What a custom agent is​

An agent is a program the server spawns when there's work to do. It:

  1. Receives a task (a chat message, a delegation from another agent, a trigger from a flow).
  2. Runs a loop: assemble context → call the LLM → execute tool calls → reflect → repeat.
  3. Eventually reports done, fails, or gets interrupted.

Every agent runs in its own process, supervised by AgentProcessManager. This isolation means your agent can crash, hang, or leak memory without affecting anything else.

Five creation paths​

There are five ways to bring an agent into Codebolt, from lowest to highest authorship cost:

PathWhat you writeGood for
Level 0 — RemixA YAML file overriding an existing agent's prompt, model, or toolsMost use cases. Start here.
Level 1 — FrameworkA small TypeScript file using the Codebolt agent frameworkCustom behaviour with batteries included
Level 2 — codeboltjsCode directly against the codeboltjs SDKNon-standard loop shape
Level 3 — Raw WebSocketThe wire protocol directlyLanguages the SDK doesn't cover
Third-Party WrappingAn adapter around an existing external agentRunning Claude Code / Codex / Cursor etc. as a Codebolt agent

Plus one sideways path: Framework Adapters let you author at level 1 but using Vercel AI SDK, LangChain, or similar frameworks instead of the native Codebolt framework.

The most important thing to know: level 0 and level 1 cover the vast majority of real use cases. Level 2 is for people building infrastructure on top of Codebolt. Level 3 is for people writing Codebolt agents in Go, Rust, or Python. Don't start higher than you need.

The framework (level 1) in one paragraph​

At level 1 you write a small TypeScript file that:

  • Declares a codeboltagent.yaml with metadata (name, description, default model, allowed tools).
  • Exports a handler that receives a typed input and returns a typed output.
  • Optionally imports patterns (Unified, Composable, Builder, Processor — see Patterns) to structure the handler without writing boilerplate.
  • Optionally registers processors that modify the prompt assembly, tool calling, or response handling (see Processors).

The framework handles: the agent loop, context assembly, tool validation, memory writes, event log integration, heartbeats. You handle: what makes your agent different from the default.

Then your agent consumes Agent Extensions — skills, action blocks, MCP tools — the same way every other agent does.

Agent patterns​

You don't write the agent loop from scratch at level 1. You pick a pattern:

  • Unified Agent — the recommended default. One config, one handler, sensible defaults. Start here.
  • Composable — build the agent out of small reusable pieces (agent, tools, orchestrator, workflow).
  • Builder — explicit builder objects for initial prompt, LLM output handling, followup prompt. Used when you need fine control over each phase.
  • Processor — decompose by loop phase (message modifier, LLM agent step, tool executor). The lowest-level of the four.

Pick Unified unless you have a specific reason not to.

The anatomy of an agent​

Every agent has:

  • A codeboltagent.yaml — metadata, manifest, entry points. See agent.yaml reference.
  • A lifecycle — start, deliberate, execute, reflect, terminate. See Lifecycle.
  • A context — the working state carried across phases. See Context.

These are the same for every agent regardless of level. The levels differ in how much code you write to express them.

Testing and debugging​

Agents are programs; test them like programs.

  • Unit tests — the framework exposes testing helpers. See Testing and debugging.
  • Replay — any production run can be replayed against a new version of your agent to see if the behaviour changes. Uses the event log.
  • Tracing — every phase is in the event log with full inputs and outputs. The UI shows it as a tree.

For systematic improvement across many runs, see Evaluation & Optimization.

Optimization​

Testing tells you whether the agent works. Optimization tells you whether it is getting better.

After your agent is stable enough to test and replay, move to Auto-Optimize Agents. That page is the agent-authoring bridge into the broader Evaluation & Optimization system.

Publishing​

When you're ready, your agent can be:

  • Private to your project — just a file in .codebolt/agents/. No publishing needed.
  • Shared within your org — pushed to a private registry.
  • Public on the marketplace — codebolt agent publish. See Publishing.

See also​