> ## Documentation Index
> Fetch the complete documentation index at: https://docs.invokehq.run/llms.txt
> Use this file to discover all available pages before exploring further.

# typescript

> Route agent tool calls through Invoke using the @invoke/sdk TypeScript package. Covers installation, client setup, invoke.call() usage, and response handling.

The `@invoke/sdk` package is the primary way to route agent tool calls through the Invoke execution runtime from TypeScript. Install it once, instantiate a client, and replace direct API calls in your agent loop with `invoke.call()`.

## Installation

```bash theme={null}
npm install @invoke/sdk
```

## Client setup

```typescript theme={null}
import { Invoke } from "@invoke/sdk"

const invoke = new Invoke({
  apiKey: process.env.INVOKE_API_KEY!,
})
```

The client reads `INVOKE_API_KEY` from the environment automatically. Pass the value explicitly to ensure TypeScript can verify the key is present at startup.

## invoke.call()

The primary method. Routes a tool call through Invoke's execution controls.

```typescript theme={null}
const result = await invoke.call({
  tool: "stripe.charge_customer",        // registered tool name
  params: { customer_id: "cust_123", amount: 2400 },
  agentId: "billing-agent",              // registered agent identity
  idempotencyKey: "charge:cust_123:2400" // deduplication handle
})
```

### Parameters

| Parameter        | Type     | Required    | Description                                     |
| ---------------- | -------- | ----------- | ----------------------------------------------- |
| `tool`           | `string` | Yes         | The registered tool name                        |
| `params`         | `object` | Yes         | Tool parameters                                 |
| `agentId`        | `string` | Yes         | The agent identity bound to a registered policy |
| `idempotencyKey` | `string` | Recommended | Deduplication key for write operations          |
| `workflowId`     | `string` | No          | Groups related calls into a single workflow run |

### Response

```typescript theme={null}
{
  status: "executed" | "blocked" | "pending_approval" | "reconciled" | "replan_required",
  final_outcome?: "already_succeeded" | "not_executed",
  idempotency_key?: string,
  retry?: "blocked" | "allowed",
  trace: TraceStep[]
}
```

| Status             | Meaning                                    |
| ------------------ | ------------------------------------------ |
| `executed`         | Tool ran, side effect landed               |
| `blocked`          | Failed a policy, scope, or identity check  |
| `pending_approval` | Staged for human review                    |
| `reconciled`       | Prior attempt succeeded, duplicate blocked |
| `replan_required`  | Live state drifted, agent should replan    |

## Error handling

```typescript theme={null}
try {
  const result = await invoke.call({ ... })
} catch (err) {
  if (err.code === "SCOPE_VIOLATION") {
    // tool not allowed for this agent
  }
  if (err.code === "AUTH_FAILED") {
    // invalid or missing API key
  }
}
```

## Next steps

* [Quick Start](/quickstart) — end-to-end example with the SDK
* [CLI](/sdk/cli) — invoke tools from the terminal
* [Authentication](/configuration/authentication) — API key setup