Skip to main content

​
Agent Control TypeScript SDK

TypeScript SDK for Agent Control.

​
Installation

npm install agent-control

pnpm add agent-control

yarn add agent-control
Requirements:
  • Node.js >=20

​
Quick Start

Create a client instance and initialize it with server and auth config: 
import { AgentControlClient } from "agent-control";

const client = new AgentControlClient();

client.init({
  agentName: "customer-support-agent",
  serverUrl: "http://localhost:8000",
  apiKey: process.env.AGENT_CONTROL_API_KEY,
});

const health = await client.system.healthCheck();
console.log(health.status, health.version);

const agents = await client.agents.list({
  limit: 20,
  name: "support",
});
console.log(agents.agents.length);

const created = await client.controls.create({
  name: "deny-pii",
});
console.log(created.controlId);
Use the default singleton if you prefer: 
import agentControl from "agent-control";

agentControl.init({
  agentName: "singleton-client",
  serverUrl: "http://localhost:8000",
  apiKey: process.env.AGENT_CONTROL_API_KEY,
});

const health = await agentControl.system.healthCheck();
console.log(health.status);

​
Monorepo Example

For a runnable example app inside this repository that installs agent-control from npm, see:
  • examples/typescript_sdk/

​
Method Naming Migration

From 0.2.0 onward, generated method names are normalized for readability (for example client.controls.list(...)). Common rename examples:
  • client.system.healthCheckHealthGet(...) -> client.system.healthCheck(...)
  • client.agents.listAgentsApiV1AgentsGet(...) -> client.agents.list(...)
  • client.controls.createControlApiV1ControlsPut(...) -> client.controls.create(...)
  • client.controls.getControlDataApiV1ControlsControlIdDataGet(...) -> client.controls.getData(...)
  • client.controls.setControlDataApiV1ControlsControlIdDataPut(...) -> client.controls.updateData(...)
  • client.evaluation.evaluateApiV1EvaluationPost(...) -> client.evaluation.evaluate(...)

​
API Namespaces

AgentControlClient exposes generated endpoint groups directly:
  • client.agents
  • client.controls
  • client.evaluation
  • client.evaluatorConfigs
  • client.evaluators
  • client.observability
  • client.policies
  • client.system
Generated method names are normalized via a deterministic, rule-generated Speakeasy overlay for ergonomic, stable naming. Example: client.agents.list(...).

​
Exported API

Current public exports:
  • default: singleton AgentControlClient
  • AgentControlClient
  • control
  • ControlViolationError
  • endpoint API types: AgentsApi, ControlsApi, EvaluationApi, EvaluatorConfigsApi, EvaluatorsApi, ObservabilityApi, PoliciesApi, SystemApi
  • generated request and response types via package root type exports (models and operations)
  • utility types: AgentControlInitOptions, StepSchema, ControlAction, EvaluationResult, JsonPrimitive, JsonValue, JsonObject

​
Current Status

Current implementation status:
  • AgentControlClient makes real API calls through the generated Speakeasy client.
  • Auth is sent using X-API-Key when apiKey is configured.
  • control(...) remains a pass-through wrapper (no enforcement behavior yet).

​
Development

make install
make speakeasy-install
make generate
make lint
make typecheck
make test
make build
Notes:
  • OpenAPI source (runtime-generated): ../../server/.generated/openapi.json
  • Method-name overrides: overlays/method-names.overlay.yaml (auto-generated by scripts/generate-method-names-overlay.py)
  • Generated code location: src/generated/
  • Speakeasy CLI version is sourced from .speakeasy/workflow.yaml and downloaded into .speakeasy/bin/
Release:
  • Package name: agent-control
  • Release guide: RELEASING.md

​
Semantic Versioning

TypeScript SDK versioning is independent from server and monorepo tags and is automated with semantic-release. Release-triggering commit prefixes for scope sdk-ts:
  • feat(sdk-ts): ... -> minor bump
  • fix(sdk-ts): ... -> patch bump
  • perf(sdk-ts): ... -> patch bump
  • refactor(sdk-ts): ... -> patch bump
  • chore(sdk-ts): ... -> patch bump
  • BREAKING CHANGE footer or ! -> major bump
To preview the next computed release locally: 
pnpm run release:dry-run