> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
last_verified: 2026-10-09
title: Client
description: Run components, follow runs, run batches, and evaluate components from your own TypeScript code
category: TypeScript SDK
hideRightSidebar: true
---

`Client` calls the AGNT5 gateway from your own code: an API server, a script, or a test. It runs components, follows runs, and evaluates components. It authenticates with a [service key](/docs/build/local-development.md#create-a-service-key).

## `new Client(options?)`

```typescript
import { Client } from '@agnt5/sdk';

const client = new Client({
  gatewayUrl: 'https://gw.agnt5.com',
  apiKey: process.env.AGNT5_API_KEY,
});
```

| Option | Description |
|---|---|
| `gatewayUrl` | The gateway. Defaults to `AGNT5_GATEWAY_URL`; set it to `https://gw.agnt5.com` for deployed workers. |
| `apiKey` | A service key. Defaults to `AGNT5_API_KEY`. |
| `deploymentId` | The deployment to run against. Leave it out when the key was created for one environment. |

## Run a component

### `client.run(component, input?, options?)`

Runs a component, waits for it to finish, and resolves to a `RunResponse`:

```typescript
const result = await client.run('order_workflow', { orderId: '4512' }, { componentType: 'workflow' });
console.log(result.status, result.output);
```

`componentType` is `'function'` (default), `'workflow'`, `'tool'`, or `'agent'`.

| `RunResponse` field | Description |
|---|---|
| `runId` | The run's ID. |
| `status` | The run's status, for example `'completed'` or `'failed'`. |
| `output` | The component's return value. |
| `error` | Error details when the run failed. |
| `durationMs` | How long the run took. |

### `client.submit(component, input?, options?)`

Starts a run and resolves at once to `{ runId, status: 'queued' }`. Follow it with:

| Method | Resolves to |
|---|---|
| `client.waitForOutput(runId, timeoutMs?, pollIntervalMs?)` | The output, once the run finishes. |
| `client.getStatus(runId)` | The `RunResponse` now. |
| `client.getResult(runId)` | The `RunResponse` with its output. |
| `client.getOutput(runId)` | The output of a finished run. |

```typescript
const { runId } = await client.submit('report_workflow', { reportId: 'r-1' }, { componentType: 'workflow' });
const report = await client.waitForOutput(runId, 60_000);
```

### `client.events(component, input?, options?)`

Starts a run and yields its events as they happen, from `run.queued` to `run.completed`:

```typescript
for await (const event of client.events('order_workflow', { orderId: '4512' }, { componentType: 'workflow' })) {
  console.log(event.eventType);
}
```

## Run a batch

`client.batch(component, items)` starts one run per item and resolves to `{ batchId, status }`. `client.getBatchStatus(batchId, true)` returns the batch's status and each item's `runId`, `status`, and `output`:

```typescript
const batch = await client.batch('score_lead', [{ leadId: 'a' }, { leadId: 'b' }]);
const status = await client.getBatchStatus(batch.batchId, true);
```

## Evaluate a component

`client.eval()` scores one input and `client.batchEval()` scores many, with built-in scorers or LLM-judge presets. See [Batch eval](/docs/improve/batch-eval.md).

## Next steps

* [Run status and output](/docs/api-reference/runs-and-traces/list-gateway-runs.md): the gateway API behind these methods.
* [Batch eval](/docs/improve/batch-eval.md): evaluate components from code.