Embedded SDK

The embedded runner reads YAML manifests from disk, registers them in an in-process runtime, and runs them locally with no network hop. Use @agntz/sdk in TypeScript or agntz in Python. Both load the same agent YAML and expose the same resource shape with language-native option names.

pnpm add @agntz/sdk

Node 20+ for TypeScript. Python 3.11+ for Python. Universal clients that cannot read from the local filesystem should use the hosted client instead.

Basic usage

index.ts

import { agntz, tool, z } from "@agntz/sdk";

const client = await agntz({
  agents: "./agents",
  tools: [
    tool({
      name: "add",
      description: "Add two numbers and return the sum",
      input: z.object({ a: z.number(), b: z.number() }),
      execute: async ({ a, b }) => a + b,
    }),
  ],
  onEvent: (event) => {
    if (event.type === "tool-call-start") console.log("→", event.toolCall.name);
  },
});

const { output, state } = await client.agents.run({
  agentId: "support",
  input: { message: "Hello" },
});

`agntz(options)`

Returns an initialized local client. Validation errors throw at startup, so misconfigured agents do not make it past process boot.

TypeScript option	Python option	Description
`agents`	`agents`	Path to a directory of `.yaml` files
`tools`	`tools`	Local tool definitions
`resources`	`resources`	Resource providers keyed by kind, such as `memory`
`store`	`store`	Optional persistence
`defaultModel`	`model_provider`	Python passes a concrete provider; TypeScript can default model config
`onEvent`	N/A	TypeScript event hook for full local event stream

Runtime API

Run an agent

const { output, state, sessionId } = await client.agents.run({
  agentId: "summarize",
  input: { text: longArticle },
  sessionId: "user-42",
});

Run with resource grants

Pass context when the run needs access to a resource such as memory. This is a namespace grant array, not the legacy contextIds scratchpad.

const { output } = await client.agents.run({
  agentId: "support-with-memory",
  input: "What do you remember about my preferences?",
  context: ["app/user/" + userId],
});

Agents that declare resources: also need matching providers at construction time:

import { createMemrez } from "@agntz/memrez";

const memrez = createMemrez();
const client = await agntz({
  agents: "./agents",
  resources: { memory: memrez.provider() },
});

See Context and resources, Resources schema, and Memory with memrez.

Stream or inspect

for await (const event of client.agents.stream({
  agentId: "summarize",
  input: { text: longArticle },
  signal: AbortSignal.timeout(30_000),
})) {
  if (event.type === "text-delta") process.stdout.write(event.text);
  if (event.type === "complete") return event.output;
}

TypeScript local streaming includes token deltas and tool-loop events. Python local streaming currently emits start and complete snapshots; use the hosted Python client for full worker SSE streaming.

Runs and traces

const { rows } = await client.runs.list({ agentId, status, limit: 10 });
const run = await client.runs.get(rows[0].id);
const trace = await client.traces.get(rows[0].id);

Persistence

import { agntz } from "@agntz/sdk";
import { sqliteStore } from "@agntz/sdk/sqlite";

const client = await agntz({
  agents: "./agents",
  store: sqliteStore("./agntz.db"),
});

The same store backs sessions, runs, and traces. Python's SQLite store persists messages and trace spans in the same file.

Errors

import { AgntzError, NotFoundError, StreamError } from "@agntz/sdk";

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

The hosted clients expose structured HTTP error classes. Local embedded execution raises Python or TypeScript runtime errors directly.

Switching to hosted

When you're ready to graduate, swap constructors and keep the same resource shape:

- import { agntz } from "@agntz/sdk";
+ import { AgntzClient } from "@agntz/client";

- const client = await agntz({ agents: "./agents" });
+ const client = new AgntzClient({
+   apiKey: process.env.AGNTZ_API_KEY!,
+   baseUrl: "https://api.agntz.co",
+ });

agents.run, runs.list, and traces.get stay the same. Local tools must be promoted to HTTP or MCP servers when the runtime moves out of your process.

← Previous

Agent-as-tool

@agntz/client