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

# Custom agents

> Integrate and run your own agent with Harbor.

Custom agents are integrations developed outside Harbor's built-in registry.
They may be local work in progress or private integrations not intended for
upstream. A custom agent can be either **installed** or **external**.

| Type            | How it runs                                                                                | Example                                                                                                        |
| --------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| Installed agent | Harbor installs and runs the agent CLI inside the task environment.                        | [Claude Code](https://github.com/harbor-framework/harbor/blob/main/src/harbor/agents/installed/claude_code.py) |
| External agent  | The agent loop runs in Harbor and controls the task environment through `BaseEnvironment`. | [Terminus-2](https://github.com/harbor-framework/harbor/blob/main/src/harbor/agents/terminus_2/terminus_2.py)  |

<Tip>
  When adding a new agent locally or integrating one into Harbor, **prefer**
  `BaseInstalledAgent`. Most agent integrations follow this design. Use
  `BaseAgent` **only when** the agent loop must remain outside the task environment.
</Tip>

Choose the base class based on where the agent runs.

<Tabs>
  <Tab title="Installed agent">
    Extend `BaseInstalledAgent` when Harbor should install and run the agent CLI
    inside the task environment.

    ```python my_agent.py theme={"system"}
    import shlex

    from harbor.agents.installed.base import (
        BaseInstalledAgent,
        with_prompt_template,
    )
    from harbor.environments.base import BaseEnvironment
    from harbor.models.agent.context import AgentContext


    class MyAgent(BaseInstalledAgent):
        @staticmethod
        def name() -> str:
            return "my-agent"

        async def install(self, environment: BaseEnvironment) -> None:
            await self.exec_as_agent(
                environment,
                command="pip install my-agent",
            )

        @with_prompt_template
        async def run(
            self,
            instruction: str,
            environment: BaseEnvironment,
            context: AgentContext,
        ) -> None:
            await self.exec_as_agent(
                environment,
                command=f"my-agent {shlex.quote(instruction)}",
            )
    ```

    Use `exec_as_root` for system packages and `exec_as_agent` for user-level
    installation and execution. Override `populate_context_post_run` to parse
    usage or trajectory data after the logs are synced.
  </Tab>

  <Tab title="External agent">
    Extend `BaseAgent` when the agent loop runs outside the task environment and
    controls it through `BaseEnvironment`.

    ```python my_agent.py theme={"system"}
    from harbor.agents.base import BaseAgent
    from harbor.environments.base import BaseEnvironment
    from harbor.models.agent.context import AgentContext


    class MyAgent(BaseAgent):
        @staticmethod
        def name() -> str:
            return "my-agent"

        def version(self) -> str | None:
            return "1.0.0"

        async def setup(self, environment: BaseEnvironment) -> None:
            pass

        async def run(
            self,
            instruction: str,
            environment: BaseEnvironment,
            context: AgentContext,
        ) -> None:
            # Call your model and act through environment.exec(...).
            pass
    ```
  </Tab>
</Tabs>

## Run a custom agent

Custom agents are not registered by name, so pass `module.path:ClassName` to
`--agent` (`-a`). The module must be importable from the Harbor process.

```bash theme={"system"}
harbor run \
  -t hello-world/hello-world \
  -a examples.agents.marker_agent:MarkerAgent
```

Use `--model` (`-m`) if the agent takes a model, `--agent-kwarg` (`--ak`) for other
constructor options, and `--agent-env` (`--ae`) for environment variables.

<Card title="Custom agent example" icon="github" href="https://github.com/harbor-framework/harbor/blob/main/examples/agents/marker_agent.py">
  See a complete `BaseAgent` implementation in the Harbor repository.
</Card>