SDKs

Two first-party clients, generated from the same contract this reference is generated from.

	Package	Import	Requires
Python	agentplat-sdk	agentplat_sdk	Python ≥ 3.11
TypeScript	@agentplat/sdk	@agentplat/sdk	Node ≥ 18.18

Neither package is on a public registry

There is no pip install agentplat-sdk and no npm i @agentplat/sdk from npmjs. A consumer pins an immutable tag — sdk-<language>-v<version> — and never a branch. Cutting a tag is an explicit release action after a green build, and an existing tag is never moved. Ask your operator for the repository coordinates.

The package names still say agentplat, which is the platform’s internal import root. It is the same product.

Python

Two optional extras, and you almost certainly want both: [httpx] for the default transport and [stream] for the WebSocket.

import os
from agentplat_sdk import AgentPlatformClient, Credential, paginate

client = AgentPlatformClient(
    "https://your-deployment.example.com",
    credential=Credential("service_key", os.environ["COBRE_KEY"]),
)

await client.assert_compatible()          # fail closed at start-up, not mid-request

run = await client.submit_run_idempotent({"agent_slug": "triage", "input": {"text": "hello"}})
async for frame in client.stream(str(run["id"])):
    if frame.type == "text.delta":
        print(frame.data["text"], end="")

async for row in paginate(client.list_runs, {"status": "failed", "limit": 100}):
    print(row["id"])

Credential is ("access_token" | "service_key" | "none", value). A service key is sent as X-Api-Key; an access token as Authorization: Bearer.

TypeScript

import { createClient, paginate } from '@agentplat/sdk';

const client = createClient({
  baseUrl: 'https://your-deployment.example.com',
  credential: { kind: 'service_key', key: process.env.COBRE_KEY! },
});

await client.assertCompatible();          // fail closed at start-up, not mid-request

const run = await client.submitRun({ agent_slug: 'triage', input: { text: 'hello' } });
for await (const frame of client.streamRun(String(run.id))) {
  if (frame.type === 'text.delta') process.stdout.write(String(frame.data['text']));
}

for await (const row of paginate(client.list_runs, { status: 'failed', limit: 100 })) {
  console.log(row.id);
}

There is no exported class — createClient returns the client, and AgentPlatformClient is its type.

Naming, which is not uniform on purpose

The generated methods keep the contract’s operation id verbatim, in snake_case, in both languages: client.list_runs, client.get_run, client.submit_run. That is what makes an operation in this reference findable in the SDK without a translation table.

The facade methods — the hand-written conveniences on top — follow each language’s own convention, and the two do not line up one-to-one:

	Python	TypeScript
Submit with an idempotency key	submit_run_idempotent	submitRun
Submit and stream in one call	submit_and_stream	submitAndStream
Stream frames	stream	streamRun
Stream and collect the result	collect	collectRun
Verify contract compatibility	assert_compatible	assertCompatible

In Python, plain submit_run is the raw generated method and does not add an idempotency key. submit_run_idempotent is the one you want.

What the facade actually buys you

• An idempotency key on every submission, generated if you do not supply one — and a network-level retry sends the same key rather than a new one.
• Streaming that follows the resumption rules: it mints a stream token, sends it in the first frame, tracks the last contiguous seq, and accumulates output text from text.delta only.
• Cursor pagination as an async iterator, so paginate is a for loop rather than a cursor variable you forget to advance.
• Retries with the platform’s own retryability, read from the error envelope rather than guessed from the status code.

Version pinning is by contract hash, not by version number

This is the part worth reading twice.

The SDK version is independent of the platform version; 0.1.0 of one says nothing about 0.1.0 of the other. Inferring compatibility from version numbers is guessing, so the SDKs do not: each build embeds the hash of the contract it was generated from, and checks it two ways.

On every request. The client sends X-Contract-Hash and compares the hash the server echoes back. By default a mismatch throws — you can set on_contract_mismatch / onContractMismatch to warn or ignore, but the default is error on purpose.

At start-up. assert_compatible() / assertCompatible() calls GET /system/capabilities and requires the contract version and the stream protocol version to match what the SDK was built against. Call it once when your process boots: a version skew discovered at start-up is an alert, and the same skew discovered on a live request is an outage.

The compatibility matrix that records which SDK build goes with which contract lives in the repository as sdks/COMPATIBILITY.json. Its list of platform versions is a list of observations, not a range — a version nobody tested is not supported, and the file deliberately does not write >=0.1.0 and claim otherwise.

Where to next

• API reference — the operation ids the generated methods are named after.
• Errors — what the SDK’s exceptions carry.