Skip to content
OpenPond
Join community
SDK/SDK overview

SDK overview

Choose SDKs for server-side execution, Dataset task submission and agent authoring.

A TypeScript server calling OpenPond uses openpond-sdk; an agent project defining behavior uses openpond-agent-sdk. Both require Node.js 22.14 or newer. Python applications can submit Dataset tasks through ponder-sdk. Portable Evals and Harness packages provide contracts for hosts that own execution.

Choose a package

PackageWhat it providesWhat your application supplies
openpond-sdkClients for Work, sandboxes, workflows, experiments, Dataset tasks and Project ActionsServer-side credentials, application authorization, output storage, and the chosen runtime
ponder-sdk (Python)Sync and async Dataset task submissionServer-side credentials, an explicit workspace and Dataset, and source/retry policy
openpond-agent-sdkTypeScript Agent source, CLI, local runtime, manifests, validation, and evalsAgent source and integrations; reviewed delivery through a Profile for hosted use
@openpond/evalsPortable evaluation protocols and helpersExecution adapters, evidence, persistence, and authorization
@openpond/harnessPortable releases and refinement policyModel streams, authorized evidence, scheduling, validation, and persistence

First server-side Work request

Install the execution client:

bash
npm install openpond-sdk

Keep the API key in your server environment. This example explicitly retains the sandbox so outputs can be inspected and saved before cleanup:

ts
import { createOpenPondClient } from "openpond-sdk"; const openpond = createOpenPondClient({ apiKey: process.env.OPENPOND_API_KEY!, }); const result = await openpond.work.run({ prompt: "Write a short project summary to /workspace/outputs/summary.md", cleanup: "keep", }); console.log(result.sandboxId, result.outputs);

This starts model and sandbox work and can incur usage charges. Review access and limits before running it. Your server owns durable output storage; download retained outputs, verify persistence, and then clean up the sandbox. For an automatic lifecycle, supply the package's persistOutput callback before choosing cleanup: "delete".

See Sandbox execution for raw commands and files, runtime lifecycle for cleanup, and budgets for resource controls. The package README owns the full executable API examples.

Configure a product client

Create one client in an application-owned server module. Bind the destination Dataset and name the exact callable Model from API → Your models:

ts
import { createOpenPondClient } from "openpond-sdk"; export const openpond = createOpenPondClient({ apiKey: process.env.OPENPOND_DATASET_API_KEY!, teamId: process.env.OPENPOND_TEAM_ID!, datasetId: process.env.OPENPOND_DATASET_ID!, serving: { baseUrl: process.env.OPENPOND_SERVING_BASE_URL!, apiKey: process.env.OPENPOND_SERVING_API_KEY!, }, models: { support: process.env.OPENPOND_MODEL_ID! }, }); const answer = await openpond.models.support.generate({ prompt: question }); const receipt = await openpond.addTask({ id: event.id, name: "Token rotation", input: { question }, });

Use a release containing the configured-client API; these examples match the maintained SDK source. serving.baseUrl is the personalized OpenAI-compatible base URL, including /v1. Naming a model uses its existing deployment; serving activation remains explicit. A Dataset producer key grants uploads to its selected Dataset. Serving uses its own authorized credential.

await addTask waits for durable task and processing storage. It suspends that async function while other work continues; it does not block the JavaScript event loop or wait for grading/training. There is no SDK delivery queue or flush command. Keep the original source-event id for retries: identical content returns the original receipt; changed content conflicts. This is an append, not an update operation. Use openpond.dataset(otherDatasetId).addTask(task) for an explicit alternate destination with suitable authorization.

Python Client and AsyncClient accept dataset_id, serving_base_url, serving_api_key and model_aliases. The sync client blocks its calling thread; async applications await AsyncClient.add_task(...) and AsyncClient.models.support.generate(...) using the existing HTTP pool.

React calls an authenticated product backend that validates the payload and uses this server client. The optional openpond-sdk/ai-sdk adapter targets AI SDK 7 with the compatible provider 3; it is a separate import with optional peer dependencies. Use the AI SDK UI-message stream conversion for useChat rather than forwarding raw model SSE. See the maintained product integration recipe for Python, cancellation, streaming and supported capabilities.

Submission does not publish a release, authorize training, create a Model or enable a schedule. If an answer succeeds but optional task delivery fails, retain and handle both outcomes. See the task-ingestion reference for fields, 128 KiB request limits and uncertain delivery. Optional OpenTelemetry exporters require an explicit task projection; arbitrary logs are not tasks.

First agent project

Use the authoring package when you want to define reusable agent behavior:

bash
npm install openpond-agent-sdk npx openpond-agent init blank-agent --cwd ./my-agent cd my-agent npx openpond-agent inspect --json npx openpond-agent validate --json

Inspection and validation do not deliver an Agent to a hosted Profile. Review setup requirements and eval configuration separately before running model-backed evaluations or publishing a package. Continue with Agent SDK, Skills, and Profiles.

Hosting and credentials

The execution SDK is server-only. Keep API keys out of browser code and NEXT_PUBLIC_* variables. Hosted models and hosted sandboxes have separate permissions and budgets. Custom model and sandbox endpoints each need their own credentials; the SDK does not borrow a credential from another service.

Portable Evals and Harness packages do not start hosted work, resolve your credentials, or persist artifacts. Import them directly when you are building your own host. Use Cloud when OpenPond should own the hosted infrastructure.

View as Markdown