agentx-js

Fast way to build AI Agents and create agent workforce

The official AgentX JavaScript/TypeScript SDK for AgentX

Why build AI agent with AgentX?

• Simplicity, Agent - Conversation - Message structure.
• Include chain-of-thoughts.
• Choose from most open and closed sourced LLM vendors.
• Built-in Voice(ASR, TTS), Image Gen, Document, CSV/excel tool, OCR, etc.
• Support all running MCP (model context protocol).
• Support RAG with built-in re-rank.
• Multi-agent workforce orchestration.
• Multiple agents working together with a designated manager agent.
• Cross vendor LLM orchestration.

Installation

npm install agentx-js

Usage

Provide an apiKey inline or set AGENTX_API_KEY as an environment variable. You can get an API key from https://app.agentx.so

Agent

import { AgentX } from 'agentx-js';

const client = new AgentX(apiKey: "<your api key here>");

// Get the list of agents you have
const agents = await client.listAgents();
console.log(agents);

Conversation

Each Conversation has agents and users tied to it.

// get agent
const myAgent = await client.getAgent(id: "<agent id here>");

// Get the list of conversation from this agent
const existingConversations = await myAgent.listConversations();
console.log(existingConversations);

// Get the list of history messages from a conversation
const lastConversation = existingConversations[existingConversations.length - 1];
const msgs = await lastConversation.listMessages();
console.log(msgs);

Chat

A chat needs to happen in the conversation. You can do stream response too, default false.

const aConversation = await myAgent.getConversation(id: "<conversation id here>");

// Regular chat
const response = await aConversation.chat("Hello, what is your name?");

// Streaming chat
const stream = aConversation.chatStream("Hello, what is your name?");
for await (const chunk of stream) {
  console.log(chunk);
}

output looks like:

{ text: null, cot: 'The user is greeting and asking for my ', botId: 'xxx' }
{ text: null, cot: 'name, which are casual, straightforward questions.', botId: 'xxx' }
{ text: null, cot: ' I can answer these directly', botId: 'xxx' }
{ text: 'Hello', cot: null, botId: 'xxx' }
{ text: '!', cot: null, botId: 'xxx' }
{ text: ' I', cot: null, botId: 'xxx' }
{ text: ' am', cot: null, botId: 'xxx' }
{ text: ' AgentX', cot: null, botId: 'xxx' }
{ text: null, cot: null, botId: 'xxx' }

*cot stands for chain-of-thoughts

Workforce

A Workforce (team) consists of multiple agents working together with a designated manager agent.

import { AgentX } from 'agentx-js';

const client = new AgentX(apiKey: "<your api key here>");

// Get the list of workforces/teams you have
const workforces = await AgentX.listWorkforces();
console.log(workforces);

// Get a specific workforce
const workforce = workforces[0]; // or any specific workforce
console.log(`Workforce: ${workforce.name}`);
console.log(`Manager: ${workforce.manager.name}`);
console.log(`Agents: ${workforce.agents.map(agent => agent.name)}`);

Workforce Conversations

// Create a new conversation with the workforce
const conversation = await workforce.newConversation();

// List all existing conversations for the workforce
const conversations = await workforce.listConversations();
console.log(conversations);

Chat with Workforce

Chat with the entire workforce team and get streaming responses from all agents.

// Stream chat with the workforce
const stream = workforce.chatStream(
  conversation.id,
  "How can you help me with this project?"
);
for await (const chunk of stream) {
  if (chunk.text) {
    process.stdout.write(chunk.text);
  }
  if (chunk.cot) {
    console.log(` [COT: ${chunk.cot}]`);
  }
}

The workforce chat allows you to leverage multiple specialized agents working together to provide comprehensive responses to your queries.

TypeScript Support

This SDK is written in TypeScript and provides full type definitions. All classes, interfaces, and methods are properly typed for better development experience.

API Reference

AgentX

The main client class for interacting with the AgentX API.

Constructor

• new AgentX(apiKey?: string) - Creates a new AgentX client instance

Methods

• getAgent(id: string): Promise<Agent> - Get a specific agent by ID
• listAgents(): Promise<Agent[]> - List all agents
• getProfile(): Promise<any> - Get the current user's profile
• static listWorkforces(): Promise<Workforce[]> - List all workforces

Agent

Represents an individual AI agent.

Properties

• id: string - Agent ID
• name: string - Agent name
• avatar?: string - Agent avatar URL
• createdAt?: string - Creation timestamp
• updatedAt?: string - Last update timestamp

Methods

• getConversation(id: string): Promise<Conversation> - Get a specific conversation
• listConversations(): Promise<Conversation[]> - List all conversations

Conversation

Represents a conversation between users and agents.

Properties

• id: string - Conversation ID
• title?: string - Conversation title
• users: string[] - User IDs in the conversation
• agents: string[] - Agent IDs in the conversation
• createdAt?: string - Creation timestamp
• updatedAt?: string - Last update timestamp

Methods

• newConversation(): Promise<Conversation> - Create a new conversation
• listMessages(): Promise<Message[]> - List all messages in the conversation
• chat(message: string, context?: number): Promise<any> - Send a message
• chatStream(message: string, context?: number): AsyncGenerator<ChatResponse> - Stream chat responses

Workforce

Represents a team of agents working together.

Properties

• id: string - Workforce ID
• name: string - Workforce name
• agents: Agent[] - List of agents in the workforce
• manager: Agent - Manager agent
• description: string - Workforce description
• image: string - Workforce image URL

Methods

• newConversation(): Promise<Conversation> - Create a new workforce conversation
• listConversations(): Promise<Conversation[]> - List all workforce conversations
• chatStream(conversationId: string, message: string, context?: number): AsyncGenerator<ChatResponse> - Stream chat with workforce

Error Handling

The SDK throws descriptive errors for various failure scenarios:

• Missing API key
• Network errors
• API errors (with status codes)
• Invalid data

try {
  const agent = await client.getAgent("invalid-id");
} catch (error) {
  console.error("Error:", error.message);
}

Environment Variables

• AGENTX_API_KEY - Your AgentX API key (optional if passed to constructor)

License

MIT License