agntz
RuntimeHostedSelf-hostDocsChangelog
Sign inQuickstart
Documentation
View .mdOptimized for LLMs — paste directly into ChatGPT, Claude, or Cursor.

Hosted client

The hosted client calls agents on agntz.co or your self-hosted worker over HTTPS. TypeScript uses @agntz/client; Python uses agntz.AgntzClient or agntz.AsyncAgntzClient. Both talk to the same worker API.

pnpm add @agntz/client

Same resource shape as the embedded SDK — code is portable between local and hosted modes once your local tools are HTTP or MCP tools.

For provider-replacement workloads, start with Provider replacement. This page is the complete client resource reference.

Basic usage

index.ts
import { AgntzClient } from "@agntz/client";

const client = new AgntzClient({
  apiKey: process.env.AGNTZ_API_KEY!,    // ar_live_...
  baseUrl: "https://api.agntz.co",       // or your self-hosted worker URL
});

const result = await client.agents.run({
  agentId: "support-agent",
  input: { message: email.body, customerId: email.from },
  retention: { mode: "result", ttlSeconds: 86_400 },
});

console.log(result.output, result.model, result.usage);

Async usage

for await (const event of client.agents.stream({
  agentId: "support-agent",
  input: { message: "Hello" },
})) {
  if (event.type === "complete") console.log("output", event.output);
  if (event.type === "error") console.error(event.error);
}

Constructor options

new AgntzClient({
  apiKey: "ar_live_...",
  baseUrl: "https://api.agntz.co",
});

API surface

client.agents.run(...)

Run an agent to completion. The normalized result includes output, state, runId, requested/resolved agent versions, provider, actual model, token usage, finish reason, response id, warnings, and retention metadata. sessionId and traceId are optional because stateless and result-only retention deliberately do not create them.

client.agents.stream(...)

Streams SSE events. Always yields a terminal complete or error event.

client.agents.start(...)

Start a durable asynchronous run using the same input, content, context, and retention fields. Use client.runs.get, client.runs.cancel, or client.runs.stream to manage it. Durable starts require result or session retention.

client.agents.import(...)

Import local manifests into hosted storage. Imported agents become available to the same run and stream APIs.

await client.agents.import({
  agents: [{ id: "support", manifest: supportYaml }],
});

Stored agents can be resolved by bare id, agent@latest, exact version timestamp, or alias when the deployment exposes version and alias administration.

client.batches.* and client.datasets.import

Create a versioned provider-native batch definition, import CSV/JSONL data, and run or compare exact manifest/dataset versions.

const dataset = await client.datasets.import({
  source: { path: "./records.jsonl" },
  format: "jsonl",
  datasetId: "records",
});
const batch = await client.batches.create(batchYaml);
const run = await client.batches.run({
  batchId: batch.id,
  datasetId: dataset.id,
  idempotencyKey: "records-2026-07-29",
});
const items = await client.batches.items(run.id);

Both sync and async Python clients expose the same resources. See Provider-native batches for the manifest subset, lifecycle, exports, callbacks, and model comparison workflow.

Runtime context grants

Pass context when a hosted run needs access to a resource such as memory. These are namespace grants minted by trusted server-side code; the model never receives a namespace parameter.

const result = await client.agents.run({
  agentId: "support-with-memory",
  input: "What do you remember about me?",
  sessionId: "user-42",
  context: ["app/user/u_123"],
});

The worker must be configured with matching resource providers. See Context and resources and Memory with memrez.

Rich content

content is an ordered array of text, image, and audio blocks. Blocks can reference URLs, base64 bytes, existing artifacts, or local files. TypeScript and Python automatically upload local files before execution.

const transcript = await client.agents.run({
  agentId: "social-transcription",
  content: [{
    type: "audio",
    file: { path: "./narration.mp3", mediaType: "audio/mpeg" },
  }],
  retention: { mode: "none", artifactTtlSeconds: 3_600 },
});

See Content, artifacts, and retention for every block source, limit, and persistence rule.

Artifacts

const artifact = await client.artifacts.upload({
  file: { path: "./frame.png", mediaType: "image/png" },
  expiresInSeconds: 3_600,
});
const metadata = await client.artifacts.get(artifact.id);
const bytes = await client.artifacts.download(artifact.id);
await client.artifacts.delete(artifact.id);

Retention

ModeBehavior
noneSynchronous stateless execution; no durable run, session, or trace
resultRedacted durable result without raw input, tool calls, session, or trace
sessionConversation history, complete run data, and trace

Set a default in the manifest and optionally tighten it per call. TTL fields use ttlSeconds / artifactTtlSeconds in TypeScript and ttl_seconds / artifact_ttl_seconds in Python.

client.runs.*

const run = await client.runs.start({ agentId, input: { /* ... */ } });
const fresh = await client.runs.get(run.id);
await client.runs.cancel(run.id);

const { rows, nextCursor } = await client.runs.list({
  agentId,
  status,
  limit,
});

client.traces.*

const trace = await client.traces.get(runId);
const list = await client.traces.list({ status: "error" });
await client.traces.delete(traceId);

Sessions

Pass the same session id across calls to continue a conversation. The hosted runtime auto-loads and appends history.

await client.agents.run({ agentId: "support", input: "Hi", sessionId: "user-42" });
await client.agents.run({ agentId: "support", input: "follow-up", sessionId: "user-42" });

Sessions are managed automatically and scoped to your user. See Sessions.

You can also import or delete sessions when migrating local state:

await client.sessions.import({
  sessions: [{ id: "user-42", messages }],
});

await client.sessions.delete("user-42");

Memory

Hosted memory APIs mirror the embedded memrez admin surface. All requests are bounded by namespace roots and runtime context grants.

await client.memory.import({ entries });

const topics = await client.memory.scan(["app/user/u_123"]);

const entries = await client.memory.list(["app/user/u_123"], {
  limit: 20,
});

await client.memory.correct(
  ["app/user/u_123"],
  entryId,
  "Prefers email receipts",
);

await client.memory.deleteEntry(["app/user/u_123"], entryId);

Datasets and evals

The hosted client manages eval definitions, datasets, async eval runs, cancellation, and latest score queries.

await client.datasets.create(dataset);
await client.evals.create(definition);

const run = await client.evals.run({
  evalId: "support-quality",
  datasetId: "refund-cases",
  agentVersion: "2026-06-18T15:30:00.000Z",
});

await client.evals.cancelRun(run.id);

const scores = await client.evals.listLatestScores({
  evalId: "support-quality",
});

Errors

import { AgntzError, AuthenticationError, NotFoundError } from "@agntz/client";

try {
  await client.agents.run({ agentId: "unknown", input: {} });
} catch (err) {
  if (err instanceof NotFoundError) {
    console.error(err.code, err.status, err.message);
  }
  if (err instanceof AgntzError && err.status === 429) {
    // Rate limited — back off
  }
}

The base AgntzError preserves the worker's stable error code. Use the code for program logic and the message for diagnostics. Structured output, manifest schema, retention, artifact, and callback failures retain their specific worker codes where supplied. See Results, streaming, and errors.

Authentication

External clients send Authorization: Bearer ar_live_.... Keys are issued in Settings → API Keys on agntz.co or your self-hosted UI. For browser usage, never embed an ar_live_* key client-side; proxy through your own backend and inject the key server-side.

Self-host with the same client

The hosted client works against any Agntz worker — the public api.agntz.co or your own deployment.

const client = new AgntzClient({
  apiKey: process.env.AGNTZ_API_KEY!,
  baseUrl: "https://agntz-worker.mycompany.com",
});
← Previous
@agntz/sdk
Next →
CLI reference