Class Agents

Agents API client for managing AI agents in the Mosaia platform

This class provides comprehensive functionality for managing AI agents, which are intelligent entities that can perform tasks, handle conversations, and execute workflows based on their configuration and assigned tools.

Features:

  • Create and configure AI agents
  • Manage agent settings and properties
  • Handle agent tools and capabilities
  • Support for chat and completion operations
  • Integration with models and tools

Remarks

Agents can be configured with different models, temperature settings, and system prompts to customize their behavior. They can also be assigned tools to extend their capabilities.

Example

Basic agent operations:

import { Mosaia } from 'mosaia-node-sdk';

const mosaia = new Mosaia({ apiKey: 'your-api-key' });
const agents = mosaia.agents;

// List all agents with filtering
const allAgents = await agents.get({
  limit: 10,
  q: 'support',
  active: true
});

// Get a specific agent
const agent = await agents.get({}, 'agent-id');

// Create a new agent
const newAgent = await agents.create({
  name: 'Customer Support Agent',
  short_description: 'AI agent for handling customer inquiries',
  model: 'gpt-4',
  temperature: 0.7,
  max_tokens: 1000,
  system_prompt: 'You are a helpful customer support agent.'
});

// Like an agent (via model instance)
await agent.like();

// Fork an agent (via model instance)
const forkedAgent = await agent.fork();

Example

Using agent chat capabilities:

// Get an agent
const agent = await agents.get({}, 'agent-id');

if (agent instanceof Agent) {
  // Use the new chat completions API
  const response = await agent.chat.completions.create({
    messages: [
      { role: 'user', content: 'How can I reset my password?' }
    ],
    temperature: 0.7,
    max_tokens: 150
  });
  
  console.log('Agent response:', response.choices[0].message.content);
}

Hierarchy

Constructors - Collections

constructor

Methods

get create update delete

Constructors - Collections

constructor

  • new Agents(uri?: string): Agents

    Creates a new Agents API client instance

    Initializes an Agents collection for managing AI agents through the API. The collection provides methods for creating, retrieving, and managing agent configurations.

    Parameters

    • uri: string = ''

      Optional base URI path (e.g., '/org/123' for org-scoped agents)

    Returns Agents

    Example

    Default initialization:

    // Uses /agent endpoint
    const agents = new Agents();

    // Create a new agent
    const agent = await agents.create({
      name: 'Support Bot',
      shortDescription: 'Customer support agent'
    });

    Example

    Organization-scoped agents:

    // Uses /org/123/agent endpoint
    const orgAgents = new Agents('/org/123');

    // List org's agents
    const agents = await orgAgents.get({
      active: true,
      limit: 10
    });

Methods

get

  • get(params: undefined | QueryParams, id: string): Promise<null | Agent>

    Get entities with optional filtering and pagination

    This method retrieves entities from the API. When called without an ID, it returns a list of entities with optional filtering and pagination. When called with an ID, it returns a specific entity.

    Parameters

    • params: undefined | QueryParams

      Optional query parameters for filtering and pagination

      • undefined
      • QueryParams

        Query parameters interface for API requests

        Used to define common query parameters that can be passed to API endpoints for filtering, sorting, and pagination.

        • [key: string]: any

          Additional custom query parameters

        • Optionalq?: string

          Search term for text-based filtering

        • Optionallimit?: number

          Maximum number of items to return

        • Optionaloffset?: number

          Number of items to skip (for offset-based pagination)

        • Optionaltags?: string[]

          Array of tags to filter by

        • Optionalactive?: boolean

          Filter by active status

        • Optionalexternal_id?: string

          Filter by external ID

    • id: string

      Optional specific entity ID to retrieve

    Returns Promise<null | Agent>

    Promise resolving to: - BatchAPIResponse when getting multiple entities - M when getting a single entity by ID - null when entity is not found

    Example

    Get multiple entities with filtering:

    const result = await collection.get({
      limit: 10,
      offset: 0,
      q: 'search term',
      active: true,
      tags: ['tag1', 'tag2']
    });

    console.log('Items:', result.data);
    console.log('Total:', result.paging?.total);

    Example

    Get single entity by ID:

    const entity = await collection.get({}, 'entity-id');
    if (entity) {
      console.log('Found:', entity.id);
    } else {
      console.log('Entity not found');
    }

    Throws

    When API request fails or response is invalid

  • get(params?: QueryParams): Promise<BatchAPIResponse<Agent>>

    Get entities with optional filtering and pagination

    This method retrieves entities from the API. When called without an ID, it returns a list of entities with optional filtering and pagination. When called with an ID, it returns a specific entity.

    Parameters

    • Optionalparams: QueryParams

      Optional query parameters for filtering and pagination

      Query parameters interface for API requests

      Used to define common query parameters that can be passed to API endpoints for filtering, sorting, and pagination.

      • [key: string]: any

        Additional custom query parameters

      • Optionalq?: string

        Search term for text-based filtering

      • Optionallimit?: number

        Maximum number of items to return

      • Optionaloffset?: number

        Number of items to skip (for offset-based pagination)

      • Optionaltags?: string[]

        Array of tags to filter by

      • Optionalactive?: boolean

        Filter by active status

      • Optionalexternal_id?: string

        Filter by external ID

    Returns Promise<BatchAPIResponse<Agent>>

    Promise resolving to: - BatchAPIResponse when getting multiple entities - M when getting a single entity by ID - null when entity is not found

    Example

    Get multiple entities with filtering:

    const result = await collection.get({
      limit: 10,
      offset: 0,
      q: 'search term',
      active: true,
      tags: ['tag1', 'tag2']
    });

    console.log('Items:', result.data);
    console.log('Total:', result.paging?.total);

    Example

    Get single entity by ID:

    const entity = await collection.get({}, 'entity-id');
    if (entity) {
      console.log('Found:', entity.id);
    } else {
      console.log('Entity not found');
    }

    Throws

    When API request fails or response is invalid

create

  • create(entity: Omit<AgentInterface, "id">): Promise<Agent>

    Create a new entity

    This method creates a new entity in the system. The entity ID will be automatically generated by the server. The method returns a new model instance initialized with the created entity's data.

    Parameters

    • entity: Omit<AgentInterface, "id">

      Entity data for the new entity (without ID)

    Returns Promise<Agent>

    Promise resolving to a new model instance

    Example

    Create a new user:

    const newUser = await users.create({
      email: 'user@example.com',
      firstName: 'John',
      lastName: 'Doe',
      active: true
    });

    console.log('Created user:', newUser.id);

    Example

    Create with external ID:

    const newAgent = await agents.create({
      name: 'Customer Support',
      shortDescription: 'AI agent for support',
      external_id: 'agent-123',
      extensors: {
        customField: 'value'
      }
    });

    Throws

    When API request fails or response is invalid

    Throws

    When required fields are missing

update

  • update(
        id: string,
        updates: Partial<AgentInterface>,
        params?: QueryParams,
    ): Promise<Agent>

    Update an existing entity

    This method updates an existing entity in the system. Only the fields provided in the update data will be updated.

    Parameters

    • id: string

      The entity ID to update

    • updates: Partial<AgentInterface>

      Partial entity data for the update (only provided fields will be updated)

    • Optionalparams: QueryParams

      Optional query parameters for the request

    Returns Promise<Agent>

    Promise resolving to the updated model instance

    Example

    Update user's email:

    const updatedUser = await users.update('user-id', {
      email: 'newemail@example.com'
    });

    Example

    Update multiple fields:

    const updatedAgent = await agents.update('agent-id', {
      name: 'Updated Agent Name',
      shortDescription: 'Updated description',
      active: false
    });

    Throws

    When API request fails or response is invalid

    Throws

    When entity ID is not provided

delete

  • delete(id: string, params?: QueryParams): Promise<void>

    Delete an entity

    This method permanently deletes an entity from the system. This action cannot be undone.

    Parameters

    • id: string

      The entity ID to delete

    • Optionalparams: QueryParams

      Optional query parameters object. Can include:

      • force: Force deletion even if entity has dependencies (boolean)

    Returns Promise<void>

    Promise that resolves when deletion is successful

    Example

    Basic deletion:

    await users.delete('user-id');

    Example

    Force delete:

    await organizations.delete('org-id', { force: true });

    Throws

    When API request fails or entity not found

    Throws

    When entity ID is not provided

Settings

Member Visibility

On This Page

Constructors - Collections
Methods