> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komodor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Import an existing agent

> Connect an agent you already run — Google ADK, LangChain, Claude Agent SDK or Agno — by generating the wrapper that registers it and reports its evidence.

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](/security-and-governance/architecture-considerations/providers). |

<Note>
  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.
</Note>

## The steps

<Steps>
  <Step title="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. |
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Generate the wrapper">
    KAOP produces the install line and the wrapper source for your framework:

    ```bash theme={null}
    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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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:

1. **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.
2. **`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.
3. **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

<CardGroup cols={2}>
  <Card title="Build from scratch" href="/manage-your-agents/build/build-from-scratch">
    Author an agent with the SDK instead of wrapping one.
  </Card>

  <Card title="Runs & evidence" href="/manage-your-agents/run/runs-evidence">
    What the imported agent now records on every run.
  </Card>

  <Card title="Fleet health" href="/manage-your-agents/optimize/fleet-health">
    Whether it stays online once it is in.
  </Card>
</CardGroup>


## Related topics

- [Build from scratch](/manage-your-agents/build/build-from-scratch.md)
- [Onboarding](/get-started/onboarding.md)
- [Memory](/manage-your-agents/build/memory.md)
- [Integrations overview](/manage-your-agents/build/integrations-overview.md)
- [Credentials & secrets](/security-and-governance/identity-and-access/credentials-secrets.md)