npm.io
6.0.0 • Published 2 weeks ago

@or-sdk/agents

Licence
Apache-2.0
Version
6.0.0
Deps
3
Size
219 kB
Vulns
0
Weekly
0

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:

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
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
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
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
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
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
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
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
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
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
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.