How it works - Komodor

Building an agent in the Komodor Agentic Operation Platform (KAOP) means deciding what it should do, what it may reach, and what starts it — then letting the platform run it as a governed worker. This page orients the Build stage: the difference between an agent and the worker that runs it, the two paths for getting an agent in the first place, and each thing you attach along the way.

What “building an agent” means here

An agent is not a script you deploy and forget. In KAOP an agent is a governed identity and behavior: its instructions, the tools it may call, the credentials it may resolve, the knowledge it may read, the schedules that start it, and the permissions enforced when it acts. Building one is therefore mostly composition. You define behavior once, then attach capability to it: Nothing on that list is mandatory. An agent with instructions and no connections is a valid agent — it just cannot see anything outside itself.

Agent versus worker

These are two different things, and the distinction matters as soon as you start debugging.

	Agent	Worker
What it is	The governed identity and behavior	The process that runs it
Where it lives	The control plane’s agent registry	Wherever you run it, or on Komodor’s infrastructure
What you do with it	Author it, attach capability, grant it access	Start it, watch it register, check whether it is online
Cardinality	One agent	One worker per agent

You build an agent. You deploy a worker. Everything in the console — runs, evidence, spend, permissions — is organized around the agent; the worker is the thing that shows as online or offline. See Architecture for how the two talk to each other.

Creating an agent

Writing the code is one half; the agent also has to exist in the control plane. Three surfaces do that, and they produce the same agent.

Console
API
MCP

Create an agent opens on a starting-point picker with three choices — Start from catalog, Build from scratch, and Import an existing agent. Choose a starting point and the wizard walks you through Agent card, Where it runs, Agent instructions, Model, MCP tools, and Triggers, then an Activate step that registers the agent, mints a worker token — shown once — and hands you what your worker needs to start. Your progress is saved as a draft as you go, so you can leave and come back.

POST /api/v1/agents creates an agent, and POST /api/v1/agents/worker-token mints a worker token for one. Use these when agent creation is part of your own provisioning. See APIs.

The agents toolset’s manage_agent tool creates and mints a worker token the same way, for a model or assistant connected to the MCP server to do it directly.

Either way the agent starts life as a draft and goes live on its worker’s first heartbeat. There is no separate activation step. If the agent already runs on your own infrastructure, the third path connects it instead of deploying anything — see Import an existing agent.

Making it available in chat

Chat is opt-in per agent, advertised on its agent card:

AGENT_SPEC = AgentSpec.from_dir(
    Path(__file__).parent,
    agent_card={"capabilities": {"chat": True, "streaming": True}},
)

See Chat & history.

Validating the deploy

These checks prove the agent is live and doing what you expect:

It registered

The agent appears in Fleet and reads as online. Registration happens on the worker’s first heartbeat — if it stays offline, the worker is not reaching the control plane, and AGENTOPS_URL being unreachable from where the worker runs is the usual cause.

It advertises what you expect

Open the agent and read its card: capabilities, tools, input schema, triggers. This is what the spec actually declared, which is not always what you meant to declare.

A real run completes

Invoke it once — Run agent on its row in Fleet, or the API — and let it finish. A run that errors here but passed locally is almost always credentials or tool access, not logic.Every agent advertises two built-in checks for this, without declaring anything:

Built-in	What it proves
Check connectivity	A canned, deterministic reply with no model, no tools and no integrations. It short-circuits before your handler runs, so it proves only that the platform can reach the worker and that runs and transcripts are flowing.
Sample run	A real run through the agent and its model with a canonical prompt, producing a live transcript. It proves the whole path, including the model.

Run them in that order to localize a failure: connectivity failing is deployment or networking; connectivity passing while the sample run fails points at the model endpoint.

Its evidence is readable

Open the run. The input, the tool calls, the reasoning, the output and the token cost should all be there. Missing spans mean the agent is doing work outside the platform’s instrumentation; missing cost means usage is not being reported. Both are worth fixing before the agent does anything real. See Runs & evidence.

Its permissions are right

Confirm what it can reach is what you intended, not what was convenient during development. See Roles & permissions.

Everything in this section

Use specialized agents

Browse the catalog and deploy a Komodor-built agent without writing code.

Integrations overview

The two connection paths, and which one your case calls for.

Integrations list

The catalog of ready-made connections, and how to connect and test one.

Integration groups

Bundle connections into a named set and attach the set to an agent.

MCP Gateway

Expose your own tools through an MCP server or an OpenAPI surface.

Credentials & secrets

Store a secret once, bind it to the agents allowed to use it, deliver it without exposing it.

Skills

Package your runbooks as reusable know-how any agent can load.

Knowledge base

Give agents your documentation and past incidents as a cited source.

Triggers & schedules

Start runs on a recurring cron schedule.

Next steps

Concepts & glossary

The vocabulary this section assumes.

Run — how it works

What happens once an agent is built and something starts it.

​What “building an agent” means here

​Agent versus worker

​Creating an agent

​Making it available in chat

​Validating the deploy

​Everything in this section