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 22+ 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" },
});

await client.close();

`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 traces = await client.traces.list({ agentId, limit: 10 });
const trace = await client.traces.get(traces.rows[0].traceId);

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. Without a configured store, TypeScript uses bounded in-memory history. SQLite persists messages, runs, and trace spans in the same file across client instances.

Call await client.close() during process shutdown to flush pending trace writes and close owned SQLite and MCP connections. The TypeScript close operation is idempotent.

Persisted stores also keep agent versions and aliases. References can be a bare id, agent@latest, an exact created-at version, or an alias. In-memory registered agents run by id only; use a store when you need version history.

Import and migration surfaces

The embedded client mirrors the hosted import APIs so local state can move to a worker later.

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

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

await client.memory?.import({
  entries: exportedMemrezEntries,
});

The CLI uses the same resources for agntz publish agents sessions memory.

Datasets and eval records

Local clients include the same dataset/eval resource shape as hosted clients. Use it to run evals before pushing an agent to a worker, then publish the definitions and results when you are ready.

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

const run = await client.evals.run({
  evalId: "support-quality",
  datasetId: "refund-cases",
});

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

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