4.23.0 • Published 2 weeks ago

@or-sdk/agents

Licence

Apache-2.0

Version

4.23.0

Deps

Size

178 kB

Vulns

Weekly

Summary Dependency Versions

Agents SDK

The @or-sdk/agents package provides a client for managing agents within the OneReach.ai ecosystem. With this client, you can perform operations such as creating, updating, retrieving, and deleting agents.

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';

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
{
items: [
  {
    id: 'agent-id',
    name: 'Agent Name',
    description: 'Agent Description',
    // ...other properties
    },
    // ...more agents
  ],
  total: 1
}

`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. Be cautious when using this method and ensure you have backups of your data if necessary.

`setAgentAction`

Set an action for an agent.

Params

agentId: string - The ID of the agent for which to set the action.
params: AgentAction - An object containing the properties of the action to set.

Example

const actionParams = {
  name: 'updateStatus',
  description: 'Updates the status of an item',
  typeDefs: `
  input UpdateStatusInput {
    id: ID!
    status: String!
  }

  type UpdateStatusResult {
    id: ID!
    status: String!
  }`,
  examples: [
    {
      description: 'Update the status of item 123 to "processed"',
      activities: [
        {
          kind: ActivityKind.Action,
          input: 'updateStatus(input: { id: "123", status: "processed" })',
        },
      ],
    },
  ],
};
const setActionResponse = await agents.setAgentAction('agent-id', actionParams);

// Example response
{
  name: 'updateStatus',
  description: 'Updates the status of an item',
  typeDefs: `
  input UpdateStatusInput {
    id: ID!
    status: String!
  }

  type UpdateStatusResult {
    id: ID!
    status: String!
  }`,
  examples: [
    {
      description: 'Update the status of item 123 to "processed"',
      activities: [
        {
          kind: ActivityKind.Action,
          input: 'updateStatus(input: { id: "123", status: "processed" })',
        },
      ],
    },
  ],
}

Note: Setting an agent action allows you to define custom behaviors and operations that the agent can perform. Ensure that the typeDefs and examples are correctly defined to match the intended functionality of the action.

`deleteAgentAction`

Delete a specific action of an agent.

Params

agentId: string - The ID of the agent whose action is to be deleted.
actionName: string - The name of the action to delete.

Example

typescript
const actionName = 'updateStatus';
await agents.deleteAgentAction('agent-id', actionName);
// No direct response, the action is deleted

`getAgentExecutions`

Retrieve a list of agent executions for a given agent.

Params

agentId: string - The ID of the agent.
params: { next?: string; maxKeys?: string; } (optional) - Optional parameters for pagination (next, maxKeys).

Example

const executions = await agents.getAgentExecutions('agent-id');

`getAgentExecution`

Retrieve the execution details of a specific agent.

Params

agentId: string - The ID of the agent.
executionId: string - The ID of the execution.
options: {} (optional) - Additional options for the API call.

Example

const execution = await agents.getAgentExecution('agent-id', 'execution-id');

`deleteAgentExecution`

Delete an agent execution.

Params

agentId: string - The ID of the agent.
executionId: string - The ID of the execution.
options: {} (optional) - Additional options for the API call.

Example

await agents.deleteAgentExecution('agent-id', 'execution-id');
// No direct response, the execution is deleted

This documentation update provides a basic overview of the @or-sdk/agents package, including installation, usage, and examples for the main methods available in the Agents class. Additional methods and their usage can be added following the same structure.

`runAgent`

Run an agent.

Params

agentId: string - The ID of the agent to run.
executionId: string - The execution ID of the agent to run.
params: RunAgentParams - An object containing the parameters for running the agent.
options: CallOptions (optional) - Additional options for the API call.

Example

await agents.runAgent(
  'agent-id',
  'execution-id',
  {
    history: []
  }
)

// example response

{
    "data": {
        "say": {
            "action": "say",
            "input": {
                "message": "Some message"
            }
        }
    }
}

`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');

Additional API reference

Methods below were missing from the package guide. Signatures and return types are taken directly from the exported source API.

`Agents`

Method	Returns	Purpose
`parseError(err: unknown)`	`Promise<void>`	See the exported TypeScript signature for behavior and constraints.
`getAgentVersions(agentId: string, options: CallOptions = {})`	`Promise<AgentVersion[]>`	Get an agent by its ID.
`releaseAgent(agentId: string, data: ReleaseVersion, options: CallOptions = {})`	`Promise<void>`	Releases agent's development version by ID.
`getAgentExecutionList(agentId: string, params: { size?: number; from?: number; orderBy?: string; order?: 'ASC' \| 'DESC'; query?: string; flowIds?: string[]; dateRange?: { field: 'updatedAt' \| 'createdAt'; from?: Date; to?: Date; }; } = {}, options: CallOptions = {})`	`Promise<ExecutionList>`	Retrieves a list of agent executions for a given agent.
`patchAgentExecution(agentId: string, executionId: string, patch: { summary?: string; }, options: CallOptions = {})`	`Promise<void>`	Partially updates an execution belonging to an agent.
`setSessionId(sessionId: string)`	`string`	Set the session ID.
`htmlToPassages(url: string, question: string, options: CallOptions = {})`	`Promise<string[]>`	Get markdown for passed url
`createAgentTestCase(cases: CreateTestCase \| CreateTestCase[])`	`Promise<void>`	Creates one or multiple agent test cases by sending a POST request to the 'agents/testing' endpoint.
`updateAgentTestCase(testCaseId: string, params: Partial<CreateTestCase>, options: CallOptions = {})`	`Promise<TestCase>`	Updates an existing agent test case with the specified parameters.
`deleteAgentTestCase(testCaseId: string, options: CallOptions = {})`	`Promise<TestCase>`	Deletes a specific agent test case by its ID.
`fetchAgentTestCases(params: { agentId: string; agentVersionId: string; }, options: CallOptions = {})`	`Promise<TestCase[]>`	Fetches the test cases for a specific agent version.
`runAgentTestCase(data: { agentId: string; agentVersionId: string; testCaseIds: string[]; })`	`Promise<void>`	Executes a set of test cases for a specific agent and its version.
`terminateAgentTestCase(data: { agentId: string; agentVersionId: string; testCaseIds: string[]; })`	`Promise<void>`	Terminates one or more agent test cases for a specific agent and version.
`configureAgent(agentId: string, agentVersionId: string, executionId: string, flowId: string, overrides: Partial<Agent>, options: CallOptions = {})`	`Promise<Agent>`	See the exported TypeScript signature for behavior and constraints.
`createResponse(requestBody: OpenAI.Responses.ResponseCreateParamsNonStreaming & Record<string, unknown>)`	`Promise<void>`	See the exported TypeScript signature for behavior and constraints.

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.