@or-sdk/agents
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
Agentsfor agent CRUD, versions, history, and completion against/v2/agents. - Use
completionfor a JSON result andcompletionStreamfor SSE. There is no Responses API wrapper. - Template methods on
Agentsstill call the v1/templatesroutes.
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
modelis aprovider/modelIdstring, for exampleopenai/gpt-4o. A value without/is rejected by the API.- The v2 prompt field is
prompt(UIMessage[]). The v1starterHistorycolumn is not written by these routes. productTypeon completion is stored on the execution the first time it is missing.listProductExecutionspages that product across every agent, newest first.sizeis at most 100.tagson completion are free-form labels on the execution (for exampleproject:42, up to 20, each matching/^[a-z0-9][a-z0-9:_./-]{0,63}$/). Tags from later requests for the same execution are merged. PasstagstolistProductExecutionsorlistExecutionsto 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? }]oncreateAgent/updateAgent). Content is read live, so editing a skill affects agents immediately andversionHashdoes not change.skillson 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.deleteSkilldoes not check agent references. - Pass
assistantMessageIdfrom the client and send the same id back on the next turn so history updates that assistant row instead of inserting another one. releaseAgentposts toPOST /v2/agents/:agentId/versionsand returns the new development version, not the version that was just released.- MCP
authsecrets are stripped from agent responses. Sending an update without the secret keeps the stored secret on the server. completion()always sendsstream: falseand returns JSON.completionStream()returns the rawResponse. Readresponse.bodyyourself. The default format is a UI message SSE stream. SetresponseFormat: '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; anerrorwhen it failed). Only one completion can run per execution: a secondstartCompletionfails with 409already_running. The result is stored in the execution history.toolCallMode: 'async'on an MCP server (agent or completion request) andasyncToolTimeout(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 anexecutionId.- When an MCP server needs OAuth,
completionStream()throwsAgentsV2RequestErrorwithstatus401 andbody.error === 'mcp_oauth_required'.body.serverscontainsauthUrlfor each server. JSONcompletion()throws the parsed axios error instead. CallparseErroron 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. |