harbor-pi-sdk-agent 0.1.0

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.

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 an OpenAI-compatible endpoint:

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' \
  --agent-kwarg 'base_url=https://api.deepseek.com'

For an Anthropic-compatible Messages endpoint:

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
base_url=https://...
thinking=xhigh

Optional kwargs:

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.