SDK overview

This section is a step-by-step track for putting Pradra inside your own application. Work through it in order and you will have: a first prediction, a tool of your own that an agent can call, a conversation that remembers, a streaming answer, and documents your model can cite.

If you only want to use the Studio, you do not need any of this — the UI covers the whole lifecycle.

The two halves

The SDK is deliberately split, and the split is the whole design.

What your product calls. Predictions, agent runs, conversations, document search. Ordinary client calls over the REST API.

What your product serves. Your own business code, running in your own process, reached by Pradra when the model needs something only your system knows. This is the half that makes Pradra an AI backend rather than an API you query.

import { Pradra, tool, runWorker } from "@pradra/sdk";

// What you call
const pradra = new Pradra({ baseUrl, apiKey, orgId });
const answer = await pradra.predict(capabilityId, { question: "…" });

// What you serve
const getOrder = tool({
  name: "get_order",
  sideEffect: "read_only",
  input: { order_id: "integer" },
  handler: ({ order_id }, ctx) => orders.find(order_id, ctx.principal.tenant_id),
});
runWorker({ baseUrl, apiKey, orgId, pool: "shop-prod", tools: [getOrder] });

Which client can do what

Be aware of this before you pick a language. TypeScript is the reference client and the only one that implements the serving half today.

The Python and Go clients are thin, zero-dependency wrappers over authenticate-and-predict. If you need the serving half in another language, the endpoints are all public and documented in the API reference — the worker protocol is a long-poll loop, not a proprietary channel.

All three are dependency-free by design: no HTTP library, no schema library, nothing to conflict with what your application already uses.

The one rule

Before you write a single tool, read this — it is the one mistake with consequences you cannot see afterwards.

Scope every handler with ctx.principal, never with the model's arguments alone.

One agent capability serves all of your customers. Pradra does not know your customers exist and cannot tell a legitimate id from a guessed one:

// WRONG — order_id came from the model, and the model can pick another one
handler: ({ order_id }) => orders.find(order_id)

// RIGHT — the tenant comes from your session, which the model never sees
handler: ({ order_id }, ctx) => orders.find(order_id, ctx.principal.tenant_id)

The failure the first version produces: a customer asks about "order 12344", the model has seen nearby order numbers in the conversation, and your handler returns someone else's order — reported back in fluent, confident prose with nothing in the answer indicating it came from the wrong account. It is not detectable from the output. principal is covered in full in Pradra as your product's AI backend.

Install

npm install @pradra/sdk     # TypeScript / JavaScript
pip install aiforge         # Python
go get github.com/aiforge/aiforge-go

The track

1. Quickstart — authenticate and make your first call.
2. Serving your own tools — connect your business code.
3. Conversations & streaming — build a chat-shaped feature.
4. Documents & retrieval — answer from your own files.
5. Webhook tools — the alternative to a worker.
6. API surface — every method, in one page.