@or-sdk/agents

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