Before adding model parsing or credential and endpoint routing, check whether
Harbor’s built-in agent auth resolution already covers
the requirement. Reuse its mappings and resolved values in your harness.
Choose the base class based on where the agent runs.
- Installed agent
- External agent
Extend Use
BaseInstalledAgent when Harbor should install and run the agent CLI
inside the task environment.my_agent.py
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.install() is skipped when users pass --ak skip_install=true, so keep it
to what could be baked into the image. Steps that must run on every trial,
such as uploading a runner script, writing credentials, or registering MCP
servers and skills, belong in configure(), which runs after install()
and also when it is skipped. Reconstruct any required in-memory state from
the installed files in configure() so it doesn’t depend on install()
running in the same process.Run a custom agent
Custom agents are not registered by name, so passmodule.path:ClassName to
--agent (-a). The module must be importable from the Harbor process.
--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). WithMODEL_CONNECTION declared, use self.model_connection.provider and
self.model_connection.model_id for the resolved provider and model ID. These
respect --skip-model-parsing-and-provider-mapping; unresolved model 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.
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.
Declare AgentCapabilities(base_url=True) only when the adapter applies --base-url.
For an SDK, pass the resolved values directly to its constructor:
MODEL_CONNECTION:
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:

