Public SDK Onboarding

Reference docs by scope

Deep Dives

• CLI

  The command reference: auth, config, artifacts, experiments, task operations, and command level troubleshooting.

• Python SDK

  Definitive SDK reference: client setup, object creation, experiments, pagination, async usage, and typed errors.

• Runtime Setup Overview

  The runtime decision guide for choosing External HTTP or Sandbox, plus the required reading per path.

• Local development

  The local agent loop: scaffold, preflight, tunnel bridging, and failure checks.

• Agent SDK (Python)

  The hosting contract: dispatch route, proxy forwarding, framework adapters, and tool schema export.

Guided flow

1) Install

pip install pipelines-sdk

If you are hosting agents:

pip install 'pipelines-sdk[odyssey]'

Canonical setup lives in the Python SDK and CLI references above.

2) Authenticate

CLI:

export PIPELINES_API_KEY="pk_live_..."
pipelines whoami

Python:

from pipelines import PipelinesClient
client = PipelinesClient(api_key="pk_live_...")

For saved config, environment precedence, and base URL targeting, see the CLI and Python SDK references.

3) Pick project and workflow

CLI:

pipelines projects list
pipelines workflow list --project-id "$PROJECT_ID"

Python:

projects = client.list_projects(page_size=10)
workflows = client.list_project_workflows(project_id=PROJECT_ID, page_size=10)

4) Verify task creation mode

CLI:

pipelines workflow creation-mode --project-id "$PROJECT_ID" --workflow-id "$WORKFLOW_ID"

Python:

mode = client.get_creation_mode(project_id=PROJECT_ID, workflow_id=WORKFLOW_ID)

If the workflow requires CSV input, seed it from a dataset instead of creating tasks directly.

5) Discover configurable fields

CLI:

pipelines workflow configurable-fields --project-id "$PROJECT_ID" --workflow-id "$WORKFLOW_ID"

Python:

fields = client.get_configurable_fields(project_id=PROJECT_ID, workflow_id=WORKFLOW_ID)

You need the node and field identifiers for prompt, model, and evaluation overrides, and for tool bindings.

6) Create one prompt artifact

CLI:

pipelines prompts template > prompt.json
pipelines prompts create --file prompt.json

Python:

prompt = client.create_prompt({...})
prompt_id = prompt["id"]

Full artifact payloads and bundle imports live in the CLI and Python SDK references.

7) Optional: add criteria and evaluation

CLI:

pipelines criteria template > criterion.json
pipelines evaluations template > evaluation.json

Python:

criterion = client.create_criterion({...})
evaluation = client.create_evaluation({...})

If you are onboarding with prompts only, skip this and run one prompt swap variant first.

8) Optional: attach tools

CLI:

pipelines tool-endpoints create --org-id "$ORG_ID" --file tool-endpoint.json
pipelines workflow tool-bindings create --workflow-id "$WORKFLOW_ID" --file tool-binding.json

Python:

endpoint = client.create_tool_endpoint(org_id=ORG_ID, payload={...})
binding = client.create_tool_binding(workflow_id=WORKFLOW_ID, payload={...})

The complete tools flow, including discovery, ground truth, and evaluation, lives in the CLI and Python SDK references.

9) Run an experiment

CLI:

pipelines workflow experiment create \
  --project-id "$PROJECT_ID" \
  --workflow-id "$WORKFLOW_ID" \
  --file experiment.json \
  --idempotency-key "sdk-onboarding-$(date +%s)" \
  --wait --summary

Python:

exp = client.create_experiment(project_id=PROJECT_ID, workflow_id=WORKFLOW_ID, payload={...})
status = client.wait_for_experiment(project_id=PROJECT_ID, workflow_id=WORKFLOW_ID, experiment_id=exp["experiment_id"])

10) Inspect copied workflows and results

Use the variant workflow ids returned by the experiment, not the source workflow id, to inspect outputs. Status and waiter helpers are documented in the CLI and Python SDK references.

Hosting an agent

If onboarding includes a hosted agent wrapper, treat the agent docs as canonical.

• Runtime decision: Runtime Setup Overview
• SDK wrapper contract: Agent SDK (Python)
• Local scaffold, preflight, and tunnel: Local development

Common first run issues

The full failure tables live in CLI troubleshooting and Python SDK troubleshooting. The most frequent cases are a missing or wrong key (401), a key without permission (403), a payload mismatch on the node or field identifiers (422), a workflow that needs CSV seeding, and stuck jobs that should be polled with the wait helpers before retrying.