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
| Package | What it provides | What your application supplies |
|---|---|---|
openpond-sdk | Clients for Work, sandboxes, workflows, experiments, Dataset tasks and Project Actions | Server-side credentials, application authorization, output storage, and the chosen runtime |
ponder-sdk (Python) | Sync and async Dataset task submission | Server-side credentials, an explicit workspace and Dataset, and source/retry policy |
openpond-agent-sdk | TypeScript Agent source, CLI, local runtime, manifests, validation, and evals | Agent source and integrations; reviewed delivery through a Profile for hosted use |
@openpond/evals | Portable evaluation protocols and helpers | Execution adapters, evidence, persistence, and authorization |
@openpond/harness | Portable releases and refinement policy | Model streams, authorized evidence, scheduling, validation, and persistence |
First server-side Work request
Install the execution client:
npm install openpond-sdkKeep the API key in your server environment. This example explicitly retains the sandbox so outputs can be inspected and saved before cleanup:
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:
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:
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 --jsonInspection 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.