harbor-pi-sdk-agent 0.1.1

Reusable Harbor custom agent that runs Pi SDK sessions and writes trajectory artifacts.

harbor-pi-sdk-agent

Run the Pi coding agent from Harbor.

Use this package when you want Harbor to launch a Pi SDK agent and collect Harbor-compatible trajectory artifacts.

Mental Model

harbor-pi-sdk-agent is a thin Harbor wrapper around the official Pi coding agent package, @mariozechner/pi-coding-agent.

It is not a provider compatibility layer. Pass Pi's provider/model-id through to this package, and let the Pi SDK registry decide the built-in model API, base URL, and request headers. Only pass base_url, model_api, or provider_headers_json when you intentionally want to override Pi's built-in provider metadata or connect to a compatible custom endpoint.

Install

Install this package into the same Python environment or image that runs Harbor.

From a private package index:

pip install harbor-pi-sdk-agent

From this private GitHub repo:

pip install git+ssh://[e-mail]/Kingwl/harbor-pi-sdk-agent.git

With uv:

uv pip install git+ssh://[e-mail]/Kingwl/harbor-pi-sdk-agent.git

Harbor should already be available in that environment. This package is loaded by import path.

Run

Set the API key for the provider you want to use:

export OPENAI_API_KEY=...

Then pass the agent import path to Harbor:

harbor run \
  --agent-import-path harbor_pi_sdk_agent.agent:PiSdkAgent \
  --agent-kwarg 'model_name=openai/gpt-4.1' \
  --agent-kwarg 'api_key_env=OPENAI_API_KEY'

For another Pi built-in provider:

export DEEPSEEK_API_KEY=...

harbor run \
  --agent-import-path harbor_pi_sdk_agent.agent:PiSdkAgent \
  --agent-kwarg 'model_name=deepseek/deepseek-v4-pro' \
  --agent-kwarg 'api_key_env=DEEPSEEK_API_KEY'

For the Pi built-in Kimi Coding provider:

export KIMI_API_KEY=...

harbor run \
  --agent-import-path harbor_pi_sdk_agent.agent:PiSdkAgent \
  --agent-kwarg 'model_name=kimi-coding/kimi-for-coding' \
  --agent-kwarg 'api_key_env=KIMI_API_KEY'

For a compatible endpoint that is not already described by Pi's provider registry:

export ANTHROPIC_API_KEY=...

harbor run \
  --agent-import-path harbor_pi_sdk_agent.agent:PiSdkAgent \
  --agent-kwarg 'model_name=anthropic/model-id' \
  --agent-kwarg 'api_key_env=ANTHROPIC_API_KEY' \
  --agent-kwarg 'base_url=https://your-anthropic-compatible-endpoint' \
  --agent-kwarg 'model_api=anthropic-messages'

Launcher Setup

In your Harbor launcher or task wrapper, use:

harbor_pi_sdk_agent.agent:PiSdkAgent

Recommended kwargs:

model_name=provider/model-id
api_key_env=PROVIDER_API_KEY
agent_label=pi-sdk
thinking=xhigh

Optional kwargs:

base_url=https://...
model_api=anthropic-messages
provider_headers_json={"User-Agent":"..."}
compaction_enabled=0
filtered_events=1
raw_events=0
max_field_chars=200000

Recommended artifacts:

/logs/agent/trajectory.json
/logs/agent/trajectory.steps.jsonl
/logs/agent/pi-filtered.jsonl
/logs/agent/pi-sdk-runner.txt

Add this only when you explicitly want raw SDK events:

/logs/agent/pi-raw.jsonl

Outputs

• trajectory.json: the main Harbor trajectory.
• trajectory.steps.jsonl: step-by-step trajectory stream for long or interrupted runs.
• pi-filtered.jsonl: compact Pi SDK event log.
• pi-raw.jsonl: raw Pi SDK event log when raw_events=1.
• pi-sdk-runner.txt: concise agent stdout.

Python Usage

Harbor usually creates the agent from the import path. If you need to construct it in Python:

from harbor_pi_sdk_agent import PiSdkAgent

agent = PiSdkAgent(
    logs_dir=logs_dir,
    model_name="openai/gpt-4.1",
    api_key_env="OPENAI_API_KEY",
)

Use this package as a Harbor agent plugin, not as a standalone command-line tool.