@agentronics/protocol

Wire-format DTOs (Zod schemas + TypeScript types) shared by every Agentronics package. Pinned alongside the SDK release.

Version: 0.3.0

Public types

The browser SDK is configured with a single Agentronics.init({...}) call. The gateway is configured with environment variables. Every option is documented below — anything not listed here is treated as forward-compatible noise and ignored.

Agentronics.init(options)

import { Agentronics } from '@agentronics/sdk'

const client = Agentronics.init({
  publishableKey: 'agtx_pk_live_…',
  siteId: 'shop-acme-com',
  auth: { verifyToken: async (method, token) => verifyOnMyServer(method, token) },
  autoDetect: true,
  trace: { gateway: true },
})

| Option | Type | Default | Description | |---|---|---|---| | publishableKey | string | required | Publishable key (agtx_pk_*). Secret keys (agtx_sk_*) throw wrong_key_kind. | | siteId | string | 'default' | Stable identifier for this site — propagated onto every trace and gateway request. | | gatewayUrl | string | 'https://gateway.agentronics.dev' | Local development only — accepts localhost / 127.0.0.1 URLs and throws on anything else. | | debug | boolean | false | Enables the console trace exporter and verbose warnings. | | auth | AuthContext | — | { verifyToken(method, token) } — how credentials passed to authenticate() are verified. See browser agents. | | autoDetect | boolean \| DetectAgentOptions | true | Detect agents on init(); false for privacy-mode hosts. | | trace.enabled | boolean | true | Master switch for the tracer. | | trace.bufferSize | number | 200 | In-memory ring buffer size before backpressure kicks in. | | trace.traceRate | number | 1.0 | Sampling rate for non-error traces (0.0–1.0). | | trace.errorRate | number | 1.0 | Sampling rate for error traces. | | trace.scrubPaths | string[] | [] | JSONPath-ish paths scrubbed before export. | | trace.gateway | boolean | false | Wire the gateway exporter (POST /v1/traces). | | trace.webhookUrl | string | — | Wire a webhook exporter for a custom sink. | | trace.exporters | TraceExporter[] | [] | Custom exporters appended to the pipeline. |

AgentronicsClient

init returns a frozen client. The full type lives in @agentronics/sdk.

client.detect()                        // → AgentIdentity | null (highest trust available)
client.authenticate({ … })             // → AgentIdentity | null
client.presentIdentity({ … })          // → staged self-declaration
client.clearIdentity()                 // hand the page back to a human
client.presentedIdentity()             // → the staged declaration, if any
client.traces()                        // → TraceEvent[] (in-memory)
client.ping()                          // gateway reachability check

For server-side authentication see the server API reference.

See packages/sdk/src/init.ts for the canonical signatures.

Gateway environment variables

The gateway is operated by Agentronics. These variables are documented for the curious and for the local-development path used by the demo + Playwright suite.

| Variable | Default | Purpose | |---|---|---| | PORT | 8787 | HTTP listen port. | | DATABASE_URL | — | Postgres connection string. Unset = in-memory adapter (dev only). | | ALLOWED_ORIGINS | http://localhost:3000,http://localhost:3001,http://localhost:3002 | Comma-separated CORS allowlist. | | CRON_SECRET | — | Required x-cron-secret for /v1/cron/* job endpoints. | | SEED_FIXTURE | false | When true, seeds the deterministic E2E fixture and installs a permissive x-clerk-user resolver. Never set in production. | | LOG_LEVEL | info | debug / info / warn / error. |

Bundle entrypoints

| Import | What it ships | Budget | |---|---|---| | @agentronics/sdk | Browser SDK — detection and agent authentication through init(). | ≤ 30 KB brotli | | @agentronics/sdk/lite | WebMCP-only init plus detectWebMcp. | ≤ 8 KB brotli | | @agentronics/sdk/server | Server-side agent authentication — see the server API. | server only | | @agentronics/sdk/next | agentronicsMiddleware() for Next.js. | server only | | @agentronics/react | Provider + hooks. Peer-deps on the SDK. | ≤ 2 KB brotli |

The CI pnpm size run in packages/sdk enforces all three plus a tree-shake budget on the Agentronics.init reachable graph.

Links

• Documentation
• Dashboard
• Changelog

License

MIT — © Agentronics.