> ## Documentation Index
> Fetch the complete documentation index at: https://agentcontrol-abhi-agent-control-auth-contract-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> TypeScript SDK client for Agent Control with generated APIs and helper utilities.

## Agent Control TypeScript SDK

TypeScript SDK for Agent Control.

## Installation

```bash theme={null}
npm install agent-control
```

```bash theme={null}
pnpm add agent-control
```

```bash theme={null}
yarn add agent-control
```

Requirements:

* Node.js `>=20`

## Quick Start

Create a client instance and initialize it with server and auth config:

```ts theme={null}
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",
  data: {
    action: { decision: "deny" },
    description: "Block SSNs in output",
    enabled: true,
    evaluator: {
      name: "regex",
      config: {
        pattern: "\\b\\d{3}-\\d{2}-\\d{4}\\b",
      },
    },
    execution: "server",
    scope: {
      stages: ["post"],
    },
    selector: {
      path: "output",
    },
  },
});
console.log(created.controlId);
```

Use the default singleton if you prefer:

```ts theme={null}
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

```bash theme={null}
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:

```bash theme={null}
pnpm run release:dry-run
```