@svantic/sdk

TypeScript A2A agent SDK for building agents that run standalone or connect to Svantic Mesh for auth, routing, and telemetry.

Purpose

• Define agents, tools, and transports that interoperate with the A2A ecosystem.
• Optional mesh integration for production deployments without forking runtime code.

Prerequisites

• Node.js (LTS) and npm.
• For HTTP-hosted agents: a compatible Express peer (optional in package.json; install when you expose HTTP routes).

Install

npm install @svantic/sdk

In the monorepo, depend via workspace or file:../../packages/sdk from consuming packages.

Subpath exports

| Import path | Role | | --- | --- | | @svantic/sdk | Core SDK entry. | | @svantic/sdk/mesh | Mesh connector and mesh-side helpers. | | @svantic/sdk/telemetry | Telemetry exporters and buffers. | | @svantic/sdk/tools | Tooling APIs and registration helpers. | | @svantic/sdk/a2a | A2A protocol–oriented types and utilities. |

Additional build-time subpaths (for example @svantic/sdk/tools/builtin) may exist—see package.json "exports".

Build

From packages/sdk:

npm install
npm run build

Tests

npx vitest run

Vitest is a dev dependency; wire a "test": "vitest run" script locally if you prefer npm test.

Telemetry

@svantic/sdk emits OpenTelemetry spans directly via @opentelemetry/api. Every capability invocation, LLM call (in smart-agent mode), and tool call becomes a span tagged with the OpenTelemetry GenAI semantic conventions — gen_ai.operation.name, gen_ai.tool.name, gen_ai.request.model, gen_ai.usage.input_tokens, etc.

• Spans flow through whatever global TracerProvider is registered in the host process. When the agent runs on the Svantic mesh, the mesh runtime wires exporting to the dashboard for you; otherwise, spans become no-ops unless you register a provider yourself.
• Trace IDs are 32-character hex (W3C trace-id); span IDs are 16-character hex (W3C parent-id).
• Context propagation uses traceparent + baggage headers on outbound A2A and mesh calls.

To add custom spans, import trace from @opentelemetry/api directly. To export to your own OpenTelemetry backend (Datadog, Honeycomb, OTLP, …), register a TracerProvider at process startup before constructing any Agent. See the telemetry guide for worked examples.

Key environment variables

Runtime variables depend on which subsystems you use (mesh URL, JWT secrets, provider keys). Configure them in the host application or deployment manifest rather than in the SDK package itself.