Custom Agents

Custom agents run over ACP from a source repository containing a harbor-agent.json manifest. Connect the repository from your profile settings before using a private one.

The template below intentionally omits source.ref, so Harbor starts from the repository's default branch and records the resolved commit SHA in the stored job config:

{
  "config": {
    "retry": {
      "exclude_exceptions": [
        "AgentTimeoutError",
        "VerifierTimeoutError",
        "RewardFileNotFoundError",
        "RewardFileEmptyError",
        "VerifierOutputParseError",
        "ApiUsageLimitError",
        "AgentSafetyRefusalError"
      ],
      "include_exceptions": []
    },
    "agents": [
      {
        "name": "acp",
        "source": {
          "path": ".",
          "repo": "<github-owner>/<custom-agent-repo>",
          "type": "github",
          "manifest": "harbor-agent.json"
        },
        "model_name": "<model-provider>/<model-name>",
        "secrets": ["<MODEL_API_KEY_ENV_VAR>"]
      }
    ],
    "datasets": [
      {
        "ref": "<dataset-ref>",
        "name": "<dataset-org>/<dataset-name>",
        "n_tasks": 3
      }
    ],
    "job_name": "<job-name>"
  },
  "job_secrets": {
    "<MODEL_API_KEY_ENV_VAR>": "<model-api-key>"
  },
  "dry_run": false
}

Replace every <...> value before submitting. To select an explicit revision, add "ref": "<branch-tag-or-commit>" inside source.

The source rules are:

• name must be acp when source is present.
• source.type must be github, and source.repo must use owner/repo form.
• source.ref is optional and accepts a branch, tag, or commit SHA. When omitted, Harbor resolves GitHub HEAD, which is the repository's configured default branch and is normally main, then records the exact commit SHA in the stored config so retries stay reproducible.
• source.path defaults to . and selects the repository directory holding the agent project.
• source.manifest defaults to harbor-agent.json and is resolved relative to source.path.
• Custom agents bring their own model credentials. Supply the key in job_secrets or store it as a hosted secret, and name it in the agent's secrets either way. A custom agent reads HOSTED_INFERENCE_TOKEN and HOSTED_INFERENCE_URL rather than the provider's own variables, so the selection is what decides which credential backs that token.

The source directory needs a locked Python project and a manifest:

{
  "schema_version": 1,
  "id": "<agent-id>",
  "version": "<agent-version>",
  "protocol": "acp",
  "runtime": {
    "kind": "python-uv",
    "python": "3.12",
    "project": ".",
    "lockfile": "uv.lock",
    "entrypoint": ["python", "-m", "<agent-module>"]
  }
}

schema_version must be 1, protocol must be acp, runtime.kind must be python-uv, and runtime.python must be "3.12". The entrypoint must be an executable that speaks ACP over standard input and output, and its first element is a command name rather than a path. Commit the manifest, the project files, and uv.lock to the repository.

To check repository access, the ref, and the manifest without launching anything, send the same request with "dry_run": true. A successful validation returns the resolved repository, the pinned commit, the manifest identity, and the access mode.