AGNT5 TypeScript SDK

Build reliable AI agents and durable workflows with TypeScript. The SDK provides typed components, workflow checkpoints, retries, streaming, tools, human-in-the-loop coordination, evaluation, and runtime observability.

Requirements

• Node.js 18 or newer
• An AGNT5 runtime for deployed execution

Installation

npm install @agnt5/sdk

Quick start

Define a typed function and start a worker:

import { fn, Worker } from '@agnt5/sdk';

const greet = fn('greet').run(async (ctx, name: string) => {
  ctx.logger.info(`Greeting ${name}`);
  return { message: `Hello, ${name}!` };
});

const worker = new Worker('hello-typescript');
await worker.run();

Imported functions, workflows, agents, tools, and scorers register with the worker. See examples/simple-worker.ts for a complete entrypoint.

Durable workflows

Use named steps for operations that should be checkpointed and replayed safely:

import { workflow } from '@agnt5/sdk';

export const prepareReport = workflow(
  'prepare-report',
  async (ctx, reportId: string) => {
    const source = await ctx.step('load-source', () => loadSource(reportId));
    const report = await ctx.step('build-report', () => buildReport(source));
    return { reportId, report };
  },
);

Keep step names and ordering stable across retries so completed work can be reused.

In pull-worker workflows, await ctx.set(key, value) and await ctx.delete(key) wait for durable state-change acknowledgments. ctx.get(key) reads the local workflow state. Before successful completion, the worker persists the final WorkflowEntity snapshot with the active lease and a version check, matching Python's workflow state persistence. State writes are ordered within each workflow; independent workflows can proceed concurrently. Standalone in-process contexts retain their local state behavior.

Package entrypoints

| Import | Purpose | | --- | --- | | @agnt5/sdk | Components, clients, workers, agents, tools, and workflows | | @agnt5/sdk/integrations | Third-party OpenAI, Agents SDK, Vercel AI SDK, and Google ADK capture | | @agnt5/sdk/serverless | Shared serverless adapters | | @agnt5/sdk/serverless/node | Node.js serverless adapter | | @agnt5/sdk/serverless/cloudflare | Cloudflare serverless adapter | | @agnt5/sdk/workerless/node | Node.js workerless HTTP adapter | | @agnt5/sdk/workerless/cloudflare | Cloudflare workerless HTTP adapter |

The default worker uses the published native binding for its supported Node.js platform. Serverless and workerless entrypoints have separate runtime requirements; review the relevant example before deploying to an edge runtime.

Third-party capture

Persistent workers automatically observe supported third-party libraries when they are installed by the application. The integrations are soft-loaded; the SDK does not install or bundle those libraries as runtime dependencies. Set AGNT5_CAPTURE=off to disable all capture, or use AGNT5_CAPTURE_OPENAI, AGNT5_CAPTURE_OPENAI_AGENTS, AGNT5_CAPTURE_VERCEL_AI, and AGNT5_CAPTURE_GOOGLE_ADK as per-library switches (off, 0, false, and no disable a switch).

Captured lifecycle events carry string provenance metadata: source identifies the integration (openai, openai_agents, vercel_ai, or google_adk) and capture_mode=observed distinguishes best-effort third-party observation from explicitly tagged native SDK events (capture_mode=native). Google ADK capture supports @google/adk 1.0.0 and newer; legacy 0.x releases are intentionally unsupported.

Vercel AI SDK 7+ is captured through its public global telemetry registry. Applications on earlier AI SDK versions can either enable the library's experimental_telemetry option with an existing OpenTelemetry provider, or use the explicit wrapper:

import * as ai from 'ai';
import { wrapAISDK } from '@agnt5/sdk/integrations';

const { generateText, streamText } = wrapAISDK(ai);

JournalSpanProcessor is also exported for applications that construct their own OpenTelemetry tracer provider. The processor and wrapper emit only when a call runs inside an AGNT5 component context, and capture failures never change the provider call's result.

The workerless/serverless entrypoint invokes the same auto-enable hook for API parity, but it does not establish AsyncLocalStorage execution context today. Third-party capture therefore remains a no-op on that path until workerless context propagation is implemented.

Examples and documentation

• examples/ includes functions, workflows, agents, streaming, HITL, MCP, chat, and workerless HTTP examples.
• docs/ contains the TypeScript SDK guides.
• AGNT5 documentation covers platform concepts and deployment.

The shared Rust foundation lives in agnt5dev/sdk-core. Vendor sandbox adapters live in agnt5dev/sdk-integrations.

Development

npm ci
npm run build:ts
npm test

Native binding development also requires a stable Rust toolchain and a sibling checkout of sdk-core.

Contributing

See CONTRIBUTING.md. Report security issues according to SECURITY.md.

License

Licensed under the Apache License 2.0.

Managed evaluation

Use client.eval() to run a registered component and score its output through POST /v1/eval. This requires a reachable AGNT5 runtime and a worker serving the component; it is not an offline experiment runner.

const result = await client.eval('greet', { name: 'Alice' }, {
  expected: 'Hello, Alice!', // Defaults to the built-in exact_match scorer.
});
console.log(result.isSuccess, result.passed, result.scores);

isSuccess reports successful component execution; passed reports the scoring outcome. A score mismatch can therefore have isSuccess === true and passed === false. Built-in scorers do not require application registration.

For multiple inputs, use client.batchEval(component, items, { maxConcurrency: 5 }). Each item is evaluated through the managed endpoint. maxConcurrency must be a positive integer. Local custom scorer calls remain available through runScorer; they do not create a managed experiment run or provide an offline dataset runner.

Release verification

A successful npm upload does not guarantee immediate package availability. npm scans new versions and may hold them for review. The release workflow waits up to 20 minutes (plus request time) for public native-package metadata and tarballs before publishing the main SDK, then verifies the main package too.

If a version remains unavailable, inspect its scan/staged status in npm using a maintainer account. Complete any required review or appeal through npm. Do not keep retrying an immutable version that returns "previously staged version"; a new version alone does not resolve a scan or approval hold.

See npm publish-time scanning and staged publishing.

Response wait

Run and stream calls wait up to 5 minutes by default. Set the per-call wait to any value from zero to 24 hours. Zero returns a pending receipt immediately after acceptance. This controls response waiting, not the workflow execution deadline: accepted work continues when the wait expires or the client disconnects.

const options = { componentType: 'workflow' as const, waitTimeoutMs: 60000 };
const result = await client.run('process_order', order, options);
for await (const event of client.events('process_order', order, options)) {
  console.log(event.eventType, event.runId);
}

waitTimeoutMs uses whole milliseconds. Run calls return 202 pending receipts directly, without additional polling. Event streams emit stream.wait_expired when the wait expires, or stream.detached for a 202 receipt. Use the run ID to read status/results. Chunk-only stream raises RunError with the run ID when waiting ends.

The default HTTP timeout allows at least the wait plus 10 seconds, or the client timeout if longer. Pass timeoutMs: 75000 to set it explicitly.

Structured assertions

structured_assertions is a reserved built-in scorer with automatic worker dispatch. In Node, the local helper calls SDK-core through the native binding:

import { structuredAssertions } from '@agnt5/sdk';

const result = structuredAssertions({
  output: [1, 2, 3],
  expected: { expected_length: 3 },
  config: { assertions: [
    { name: 'unique_ids', expr: 'unique(output_json)' },
    { name: 'count', expr: 'size(output_json) == expected.expected_length' },
  ] },
});

The score is the fraction of assertions that pass; score_threshold defaults to

1. Configuration and input errors always fail. See the SDK-core contract for supported expressions and execution limits. Edge clients may submit recipes for runtime execution; local evaluation requires Node and the matching native binding.