> ## Documentation Index
> Fetch the complete documentation index at: https://agentcontrol-docs-add-source-code-notes-to-examples.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](https://github.com/agentcontrol/agent-control).

## Installation

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

```bash theme={null}
npm 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 + 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",
});
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/`](/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/response types via package root type exports (models + 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/`