Import an existing agent - Komodor

Import connects an agent you are already running to the Komodor Agentic Operation Platform (KAOP), rather than rebuilding it here. Your agent’s behaviour stays in your code and keeps running where it runs; KAOP generates a thin wrapper that registers it, receives its work, and reports its evidence.

Prepare before you start


A working agent	It already runs and produces useful output. Import connects it; it does not fix it.
A supported framework, or none	Google ADK, LangChain, Claude Agent SDK and Agno each have an adapter. Anything else uses the bare worker API and you wire the call yourself.
Python 3.10 or later where the agent runs	The wrapper is a Python package, even when the agent it wraps is not.
Somewhere the agent can reach the control plane from	Outbound only. Nothing needs to reach into your environment.
A model provider	The imported agent keeps calling whatever model it already calls, unless you point it at a registered provider. See Providers.

The agent does not have to be reachable from KAOP, or have a public address. The wrapper opens the connection outward and claims work over it.

The steps

Framework

Pick the framework your agent is built on. The choice decides which adapter the generated wrapper uses and what it captures automatically:

Framework	What the adapter does
Google ADK	Wraps your `Runner`. Tool calls and sub-agents arrive as spans.
LangChain	Wraps a chain or agent executor through the callback handler.
Claude Agent SDK	Wraps `query()`. Hooks carry tool use and cost.
Agno	Wraps a team or a single agent run handler.
Something else	A custom loop, or a framework with no adapter yet. You get the bare worker API and connect it yourself.

Agent card

Name the agent and give it an id and a description. This is the identity KAOP governs — what appears in Fleet, what permissions attach to, and what runs are attributed to. It is independent of whatever your code calls itself.

Where it runs

Keep the agent where it already runs, or move it to Komodor-hosted. Importing usually means keeping it in place, which is the point: the code and its network access do not move.

Model, tools and triggers

The same wizard steps as any other agent — Model, MCP tools, Integrations, Triggers, Permissions. An imported agent can skip most of them and keep using its own model and tools, or adopt KAOP’s so that credentials, guardrails and spend attribution apply to it too.

Generate the wrapper

KAOP produces the install line and the wrapper source for your framework:

pip install "komodor-agentops[langchain]"

The wrapper builds its spec with AgentSpec.from_dir, which reads agent-spec.yaml from the directory alongside it. That path — rather than constructing the spec in code — is what applies the AGENTOPS_AGENT_ID override and picks up agent.md, labels and provenance.

Set three variables and start it

The wrapper authenticates with three environment variables:

Variable	What it is
`AGENTOPS_URL`	Your account host. Must be reachable from where the agent runs.
`AGENTOPS_AGENT_ID`	The agent id from the card step.
`AGENTOPS_WORKER_TOKEN`	Issued during import, and shown once.

Start the agent as you normally would. The wrapper registers it on the first heartbeat.

Validate the import

The Verify step watches for the agent rather than asking you to confirm it, and updates on its own as soon as the agent connects:

Signal	What it means
First heartbeat received	The wrapper reached the control plane and registered. Until this arrives, the agent shows as offline.
Roles applied	Permissions attached on connect.
What your agent says it is	The card the wrapper advertised — its capabilities, tools and input schema. Compare it with what you expected; a mismatch here means the wrapper is reading a different spec than you think.

If the first heartbeat does not arrive, check these in order:

All three variables are set, and AGENTOPS_AGENT_ID matches the id the token was minted for. A token bound to a different agent authenticates as that one.
AGENTOPS_URL is reachable from where the agent runs — not only from your own machine. This is the most common cause: the value was tested from a laptop and the agent runs in a cluster.
The spec is the one you think it is. If it is built in code rather than loaded from agent-spec.yaml, the environment override does not apply and the agent registers under a different id.

Once the heartbeat lands, run it once and read the evidence. Its input, tool calls, output and cost are recorded the same way as any other agent’s — that is the import working, not just connecting.

Next steps

Build from scratch

Author an agent with the SDK instead of wrapping one.

Runs & evidence

What the imported agent now records on every run.

Fleet health

Whether it stays online once it is in.

​Prepare before you start

​The steps

​Validate the import

​Next steps

Build from scratch

Runs & evidence

Fleet health

Prepare before you start

The steps

Validate the import

Next steps