# @or-sdk/agents

> OneReach SDK client for Agents

Latest version **6.0.0** (published 2026-11-05) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @or-sdk/agents
pnpm add @or-sdk/agents
yarn add @or-sdk/agents
bun add @or-sdk/agents
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 6.0.0 |
| Published | 2026-11-05 |
| First published | 2024-03-19 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 219.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | onereach.admin, user.npm |

## Links

- npm: https://www.npmjs.com/package/@or-sdk/agents
- npm.io page: https://npm.io/package/@or-sdk/agents

## Dependencies (3)

- [@or-sdk/base](https://npm.io/package/@or-sdk/base.md) ^0.45.3
- [@or-sdk/bots](https://npm.io/package/@or-sdk/bots.md) ^1.9.3
- [@or-sdk/deployer](https://npm.io/package/@or-sdk/deployer.md) ^1.9.3

## Recent versions

- 6.0.0 (latest) — 2026-11-05
- 5.0.1-beta.4438.0 (beta) — 2026-11-05
- 5.0.1-beta.4437.0 — 2026-11-05
- 4.24.0 — 2026-11-05
- 4.23.5-beta.4433.0 — 2026-11-05
- 4.23.4 — 2026-10-29
- 4.23.4-beta.4425.0 — 2026-10-29
- 4.23.3 — 2026-10-29
- 4.23.3-beta.4422.0 — 2026-10-29
- 4.23.3-beta.4421.0 — 2026-10-28
- 4.23.3-beta.4419.0 — 2026-10-27
- 4.23.3-beta.4418.0 — 2026-10-26
- 4.23.3-beta.4410.0 — 2026-10-21
- 4.23.3-beta.4406.0 — 2026-10-20
- 4.23.3-beta.4405.0 — 2026-10-20
- … 315 more at https://npm.io/package/@or-sdk/agents/versions

## README

# Agents SDK

The `@or-sdk/agents` package provides a client for the agents v2 API (`/v2/agents`): agents, versions, history, and completion. Template methods still call the v1 `/templates` routes. `Agents` and `AgentsV2` are the same class.

## Installation

To install the package, run the following command:
```
$ npm install @or-sdk/agents
```

## Usage
To use the `Agents` client, you need to create an instance of the class with the appropriate configuration options. Here is an example:
```ts
import { Agents } from '@or-sdk/agents';
// AgentsV2 is the same class

const agents = new Agents({
  token: 'my-account-token-string',
  serviceUrl: 'http://example.agents/endpoint',
  accountId: 'your-account-id',
  feature: 'master', // service feature name
});
```

Once you have an instance of the `Agents` client, you can use its methods to interact with the agents system. The available methods are:

### `createAgent`
Create a new agent.

#### Params
- `params`: `CreateAgent` - An object containing the properties of the agent to create.

#### Example
```typescript
const newAgent = await agents.createAgent({
  name: 'New Agent',
  description: 'Description of the new agent',
  // ...other properties
});

// Example response
{
  id: 'new-agent-id',
  name: 'New Agent',
  description: 'Description of the new agent',
  // ...other properties
}
```


### `findAgents`
Find agents with optional pagination and query.

#### Params
- `params`: `FindAgentsOptions` (optional) - Optional find parameters.

#### Example
```typescript
const agentsList = await agents.findAgents({
query: 'search query',
size: 10,
from: 0,
});
// Example response: an array, not `{ items, total }`
[
  {
    id: 'agent-id',
    name: 'Agent Name',
    description: 'Agent Description',
  },
]
```

### `getAgent`
Get an agent by its ID.

#### Params

- `agentId`: `string` - The ID of the agent to retrieve.

#### Example
```typescript
const agent = await agents.getAgent('agent-id');

// Example response
{
  id: 'agent-id',
  name: 'Agent Name',
  description: 'Agent Description',
  // ...other properties
}
```

### `updateAgent`
Update an agent by its ID.

#### Params
- `agentId`: `string` - The ID of the agent to update.
- `params`: `UpdateAgent` - The update agent parameters.

#### Example
```typescript
const updatedAgent = await agents.updateAgent('agent-id', {
  name: 'Updated Agent Name',
  description: 'Updated description',
  // ...other update parameters
});

// Example response
{
  id: 'agent-id',
  name: 'Updated Agent Name',
  description: 'Updated description',
  // ...other properties
}
```

### `deleteAgent`
Delete an agent by its ID.

#### Params
- `agentId`: `string` - The ID of the agent to delete.

#### Example
```typescript
await agents.deleteAgent('agent-id');
// No direct response, the agent is deleted
```

**Note:** Deleting an agent is a permanent operation, and the removed data cannot be recovered.

### `findTemplates`
Find templates with optional pagination and query.

#### Params
- `params`: `FindTemplatesOptions` (optional) - Optional find parameters.

#### Example
```typescript
const templatesList = await agents.findTemplates({
  query: 'search query',
  size: 10,
  from: 0,
});

// Example response
{
items: [
  {
    id: 'template-id',
    name: 'Template Name',
    description: 'Template Description',
    // ...other properties
    },
    // ...more templates
  ],
  total: 1
}
```

### `getTemplate`

Get a template by its ID.

#### Params

- `templateId`: `string` - The ID of the template to retrieve.

#### Example
```typescript
const template = await agents.getTemplate('template-id');
```

### `createTemplate`
Create a new template.

#### Params
- `params`: `CreateTemplateParams` - An object containing the properties of the template to create.

#### Example
```typescript
const newTemplate = await agents.createTemplate({
  agentId: 'agent-id',
  flowIds: ['flow-id-1', 'flow-id-2'],
});
```

### `deleteTemplate`

Delete a template by its ID.

#### Params
- `templateId`: `string` - The ID of the template to delete.

#### Example
```typescript
await agents.deleteTemplate('template-id');
```


## Agents v2 API

`Agents` is the v2 client. `AgentsV2` is the same class. Completion replaces the old `createResponse` helper, so this package does not depend on `openai`.

### When to use

- Use `Agents` for agent CRUD, versions, history, and completion against `/v2/agents`.
- Use `completion` for a JSON result and `completionStream` for SSE. There is no Responses API wrapper.
- Template methods on `Agents` still call the v1 `/templates` routes.

### Usage

```ts
import { Agents, ProductType } from '@or-sdk/agents';

const agents = new Agents({
  token: 'my-account-token-string',
  serviceUrl: 'http://example.agents/endpoint',
  accountId: 'your-account-id',
});

const agent = await agents.createAgent({
  name: 'Helper',
  model: 'openai/gpt-4o-mini',
  objective: 'Answer briefly.',
});

const result = await agents.completion(agent.id, {
  model: 'openai/gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello' }],
});

const stream = await agents.completionStream(agent.id, {
  model: 'openai/gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello' }],
  responseFormat: 'ui',
});
// stream.body is a UI message SSE stream

const history = await agents.listExecutions(agent.id, { productType: ProductType.Chat });
```

### Pitfalls

- `model` is a `provider/modelId` string, for example `openai/gpt-4o`. A value without `/` is rejected by the API.
- The v2 prompt field is `prompt` (UIMessage[]). The v1 `starterHistory` column is not written by these routes.
- `productType` on completion is stored on the execution the first time it is missing. `listProductExecutions` pages that product across every agent, newest first. `size` is at most 100.
- `tags` on completion are free-form labels on the execution (for example `project:42`, up to 20, each matching `/^[a-z0-9][a-z0-9:_./-]{0,63}$/`). Tags from later requests for the same execution are merged. Pass `tags` to `listProductExecutions` or `listExecutions` to keep only executions that contain all of them. There is no separate project entity.
- Skills live in the account library and agents reference them by name (`skills: [{ name, disabled? }]` on `createAgent` / `updateAgent`). Content is read live, so editing a skill affects agents immediately and `versionHash` does not change. `skills` on a completion request replaces the agent's list entirely. A missing or invalid skill (from the agent or the request) fails the completion with 400 before the model is called. `deleteSkill` does not check agent references.
- Pass `assistantMessageId` from the client and send the same id back on the next turn so history updates that assistant row instead of inserting another one.
- `releaseAgent` posts to `POST /v2/agents/:agentId/versions` and returns the new development version, not the version that was just released.
- MCP `auth` secrets are stripped from agent responses. Sending an update without the secret keeps the stored secret on the server.
- `completion()` always sends `stream: false` and returns JSON. `completionStream()` returns the raw `Response`. Read `response.body` yourself. The default format is a UI message SSE stream. Set `responseFormat: 'text'` for a plain text stream.
- `startCompletion(agentId, { executionId, ...body })` starts the completion on the server and returns the run at once (HTTP 202); it never streams. `getRun(agentId, executionId)` reads its status (`running`, `completed`, `failed`; an `error` when it failed). Only one completion can run per execution: a second `startCompletion` fails with 409 `already_running`. The result is stored in the execution history.
- `toolCallMode: 'async'` on an MCP server (agent or completion request) and `asyncToolTimeout` (seconds, 0 turns it off) on an agent or completion make slow tool calls run in the background. The model gets a placeholder at once, and the server starts a follow-up turn when the real result arrives. Both need an `executionId`.
- When an MCP server needs OAuth, `completionStream()` throws `AgentsV2RequestError` with `status` 401 and `body.error === 'mcp_oauth_required'`. `body.servers` contains `authUrl` for each server. JSON `completion()` throws the parsed axios error instead. Call `parseError` on it.

### Method map

| Method | Route | Purpose |
|---|---|---|
| `createAgent` | `POST v2/agents` | Create an agent. 409 when the name already exists. |
| `findAgents` | `GET v2/agents` | List agents. Returns an array. |
| `getAgent` | `GET v2/agents/:agentId` | Get an agent. `versionId` reads a released version. |
| `updateAgent` | `PUT v2/agents/:agentId` | Update the development version. |
| `deleteAgent` | `DELETE v2/agents/:agentId` | Delete an agent. |
| `listVersions` | `GET v2/agents/:agentId/versions` | List version summaries. |
| `getVersion` | `GET v2/agents/:agentId/versions/:versionId` | Get one stored version document. |
| `releaseAgent` | `POST v2/agents/:agentId/versions` | Release the development version. |
| `listExecutions` | `GET v2/agents/:agentId/history` | List executions. Optional `tags` filter. |
| `listProductExecutions` | `GET v2/products/:productType/executions` | Executions for a product across all agents, newest first. Optional `tags` filter. |
| `getHistory` | `GET v2/agents/:agentId/history/:executionId` | Get stored messages. |
| `deleteExecution` | `DELETE v2/agents/:agentId/history/:executionId` | Delete an execution and its messages. |
| `listSkills` | `GET v2/skills` | List skills with descriptions, no content. |
| `getSkill` | `GET v2/skills/:name` | Get a skill with all its files. |
| `createSkill` | `POST v2/skills` | Create a skill from `{ name, files }`. 409 when the name is taken. |
| `updateSkill` | `PUT v2/skills/:name` | Replace the whole package. Unlisted files are removed. |
| `deleteSkill` | `DELETE v2/skills/:name` | Delete a skill. Agent references are not checked. |
| `completion` | `POST v2/agents/:agentId/completion` | Non-streaming JSON completion. |
| `completionStream` | `POST v2/agents/:agentId/completion` | Streaming completion. Returns `Response`. |
| `findTemplates` / `getTemplate` / `createTemplate` / `deleteTemplate` | `templates` | v1 template routes. |
| `setSessionId` | header `x-or-session-id` | Session id for later requests. |
| `parseError` |  | Parse an axios error from a JSON call. |

Full signatures are in `src/v2/types.ts` and `src/v2/AgentsV2.ts`.

## Exported utility reference

| Function | Returns | Purpose |
|---|---|---|
| `createErrorParser(...processors: ErrorProcessor<E>[])` | `unknown` | Exported utility; see its TypeScript signature for behavior. |
| `parseAxiosError(e: AxiosError)` | `Error` | Exported utility; see its TypeScript signature for behavior. |
| `isOrNetworkError(err: unknown)` | `err is OrNetworkError` | Exported utility; see its TypeScript signature for behavior. |

---
_Source: https://npm.io/package/@or-sdk/agents · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
