Custom agents

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
External 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.

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.

Agent auth resolution

For inference connections, accept the same model slug users pass to other agents (model lookup). Use self._parse_model_name(self.model_name) to obtain LiteLLM’s resolved provider and model ID while respecting --skip-model-parsing-and-provider-mapping. Unresolved names remain unchanged. For a LiteLLM client, pass self.model_name verbatim instead of rebuilding a slug from those parts. Handle client-specific formatting inside the adapter, and preserve native identifiers and authentication for other backends, such as Tinker. Declare the connection your runtime supports: Use agent_provider_access for the agent’s credential and endpoint input names. These are fallbacks after the selected provider’s names within each environment source.

from harbor.agents.agent_auth_resolution import ModelConnectionSpec, ProviderAccess
from harbor.models.model_api_format import ModelApiFormat

class MyAgent(BaseInstalledAgent):
    MODEL_CONNECTION = ModelConnectionSpec(
        default_provider="openai",
        agent_provider_access=ProviderAccess(
            api_key_candidate_names=["MY_AGENT_API_KEY", "OPENAI_API_KEY"],
            base_url_candidate_names=["MY_AGENT_BASE_URL"],
        ),
        supported_api_formats=[ModelApiFormat.OPENAI_CHAT_COMPLETIONS],
        default_api_format_by_provider={
            "default": ModelApiFormat.OPENAI_CHAT_COMPLETIONS,
        },
    )

In default_api_format_by_provider, a provider match takes precedence over "default". Use ModelApiFormat members in declarations and resolved connections. Native defaults can include formats that the adapter does not support as explicit overrides. Set supports_overriding_base_url=False if the adapter cannot apply --base-url. For an SDK, pass the resolved values directly to its constructor:

connection = self.model_connection
client = Client(api_key=connection.api_key, base_url=connection.base_url)
model_id = self._parse_model_name(self.model_name)[1]

For a client that reads environment variables, also declare the variable names it reads in MODEL_CONNECTION:

api_key_destination_names={"default": "MY_CLIENT_API_KEY"},
base_url_destination_names={"default": "MY_CLIENT_BASE_URL"},

Pass self.model_connection.env to the client’s execution environment. The resolver selects the credential and maps it to the declared variable. In either dictionary, additional keys can name API formats or providers. A matching API format takes precedence over a provider match, then "default". Adapter hooks can override the destination for native configuration or authentication. When no entry matches, Harbor forwards the selected value using the provider’s or selected transport’s environment variable names. Provider extra_env_names are forwarded independently, using scoped agent values before ambient values. Preserve native settings unless the corresponding common override is supplied. Declare only API formats your adapter implements, and reject unsupported formats clearly. Inspect your declaration with:

harbor agent auth module.path:MyAgent --json

See auth resolution settings for common options and credential precedence.

Getting started

Core concepts

Tasks

Datasets

Jobs

Agents

Sandboxes

Plugins

Results

Harbor Hub

Hosted Harbor

Rewardkit

Tutorials

Open Source Policy

Telemetry

Run a custom agent

Custom agent example

Agent auth resolution

​Run a custom agent

Custom agent example

​Agent auth resolution

Run a custom agent

Agent auth resolution