---

name: integrations description: "Extend Harbor with custom agents, environments, plugins, bridges, model connections, MCP/skills, simulated users, and optional first-party integrations; verify extension contracts without invoking external services by accident." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Extend Harbor integrations

Use this skill when the requested change is framework extension work: a custom agent or environment, an import-path integration, a job plugin, a model connection, an ACP/bridge adapter, MCP or injected skills support, a simulated user, or an optional provider such as LangSmith. Keep the extension self- contained and prove its contract with mocked or local tests before attempting a real provider, model, Docker daemon, or network service.

Route before editing

• Run an existing task/dataset or select an agent/model/provider: route to run-evaluate. Passing an already implemented custom import path to a run is execution work there.
• Author a task-side MCP declaration, verifier, RewardKit criterion, or benchmark package: route to author-benchmarks. Implementing the MCP server, bridge, or framework adapter stays here.
• Inspect, compare, or publish completed results: route to analyze-publish; do not add result interpretation to this skill.
• Experimental map/reduce execution: route to exec-map-reduce.

Read the focused references in this order:

1. extension-contracts.md
2. optional-integrations.md
3. mcp-skills-bridges.md
4. troubleshooting.md

Safe extension workflow

1. Normalize the extension boundary. Record the target class, public import path, lifecycle owner, configuration fields, supported operating systems/backends, credentials, and a CPU/local acceptance test. Decide whether the work is an external agent, installed agent, environment, JobPlugin, bridge, or configuration-only adapter.
2. Check the installed surface first. Run harbor --version and inspect the relevant --help output. In Python, inspect the installed BaseAgent, BaseInstalledAgent, BaseEnvironment, AgentFactory, and EnvironmentFactory signatures. The source checkout and installed distribution can differ; record the version used for verification.
3. Implement through a public contract. Use module.path:ClassName for a custom AgentConfig.import_path or EnvironmentConfig.import_path. Do not edit the built-in name/type registries unless the extension is intentionally first-party. A custom class is instantiated by the factory with framework constructor arguments plus kwargs; reject unknown or unsafe options clearly.
4. Respect lifecycle and capability gates. Agents must populate AgentContext during run; environments must enforce or reject resource, network, OS, and compose requirements. Advertise SUPPORTS_WINDOWS, resume, trajectory, handoff, ATIF, and SUPPORTED_BRIDGES accurately. A missing capability must fail during preflight, not after a costly run starts.
5. Separate optional layers. Import only the selected provider/plugin extra. Run provider preflight() before queueing trials and distinguish a missing SDK from missing credentials, a bad endpoint, and a service failure. Never use harbor[cloud] or a real API as a substitute for a narrow import or mocked contract test.
6. Resolve configuration before execution. Validate agent/environment config, import the class, merge task and runtime MCP servers by name, resolve skills and their destination, and validate bridge target support. Show the resulting provider/model/environment and credential gates before a real run.
7. Test in layers. Start with import and constructor tests, then factory wiring, config validation, lifecycle tests using fake environments, optional provider tests with SDK/network calls mocked, and only then an explicitly approved end-to-end smoke test. Do not put tests, logs, credentials, or generated reports in this runtime skill directory.

Minimal contracts

An external custom agent subclasses harbor.agents.base.BaseAgent and provides name(), version(), async setup(environment), and async run(instruction, environment, context). Its constructor should accept the framework's logs_dir and model_name and forward supported common kwargs to super(). Use environment.exec() with the configured default user; do not assume root.

An installed agent subclasses harbor.agents.installed.base.BaseInstalledAgent. Add install(environment) for tool setup, use the base execution helpers, and decorate prompt-aware run() methods with with_prompt_template when appropriate. Declare native configuration, model connection, system packages, error patterns, and trajectory capabilities instead of hiding them in arbitrary CLI code.

An environment subclasses harbor.environments.base.BaseEnvironment. Implement type(), _validate_definition(), start(force_build), stop(delete), upload_file, upload_dir, download_file, download_dir, and exec; override capabilities, resource_capabilities(), and preflight() when the provider supports those surfaces. A custom environment can use an arbitrary string from type() and EnvironmentConfig.import_path, so it does not need a new enum member.

A job plugin is a class satisfying harbor.models.job.plugin.JobPlugin (or subclassing BaseJobPlugin) with async on_job_start(job) and async on_job_end(job_result). Register a package under the harbor.plugins entry-point group to allow a short plugin name, or pass its full module:ClassName import path. Plugins are attached at job start; their external mutations and credentials require explicit approval.

Model connections are declarative. An installed agent may set a ModelConnectionSpec with a fixed/default provider, agent-specific key and base-URL environment names, and optional provider-variable passthrough. The resolver derives a provider from model_name when needed, honors explicit agent environment values over ambient values, and only exposes selected variables to the agent. A model string or parsed connection is not proof that credentials or an endpoint are usable.

MCP servers, skills, ACP, simulated users, RewardKit, and LangSmith have additional data and lifecycle rules; use the bundled references rather than copying agent-specific setup commands into a new extension.

Completion record

Report the files changed, installed version and signatures checked, import and config tests run, optional backends/services not exercised, and unresolved capability or credential limits. Do not claim an extension is provider-ready, Windows-compatible, resumable, ACP-compatible, or model-connected unless that specific gate was checked.