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.

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 { output, state } = await client.agents.run({
  agentId: "support-agent",
  input: { message: email.body, customerId: email.from },
});

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. Returns { output, state, sessionId, replies } in TypeScript and the same fields as Python attributes such as result.session_id.

`client.agents.stream(...)`

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

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.

`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.

Errors

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

try {
  await client.agents.run({ agentId: "unknown", input: {} });
} catch (err) {
  if (err instanceof NotFoundError) {
    // 404 — unknown agent id
  }
  if (err instanceof RateLimitError) {
    // 429 — back off
  }
}

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

CLI reference