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
External agent	The agent loop runs in Harbor and controls the task environment through BaseEnvironment.	Terminus-2

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.

Choose the base class based on where the agent runs.

Installed agent

Extend BaseInstalledAgent when Harbor should install and run the agent CLI inside the task environment.

my_agent.py

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.

External agent

Extend BaseAgent when the agent loop runs outside the task environment and controls it through BaseEnvironment.

my_agent.py

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

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.

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.

Custom agent example

See a complete BaseAgent implementation in the Harbor repository.