Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xhipai.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Transport Overview

The Agentium transport layer exposes agents, teams, and workflows over HTTP (Express) and WebSockets (Socket.IO). It is optional—install @agentium/transport only when you need to serve agents via REST or real-time connections.

​
Architecture

Express Router

createAgentRouter() returns an Express router with REST endpoints for agents, teams, and workflows.

Socket.IO Gateway

createAgentGateway() attaches real-time handlers to a Socket.IO server for streaming agent responses.
Both can run in the same Node.js process. Mount the router on your Express app and attach the gateway to your Socket.IO instance.

​
Optional Install

The transport package is separate from the core. Install it when you need HTTP or WebSocket exposure: 
npm install @agentium/transport express socket.io

​
Quick Start

Agents auto-register into a global registry on construction. The transport layer discovers them dynamically — no need to wire agents into router or gateway options manually. 
import express from "express";
import { createServer } from "http";
import { Server } from "socket.io";
import { createAgentRouter, createAgentGateway } from "@agentium/transport";
import { Agent, openai } from "@agentium/core";

// Agents auto-register on construction
new Agent({ name: "assistant", model: openai("gpt-4o"), instructions: "You are helpful." });

const app = express();
app.use(express.json());
app.use("/api", createAgentRouter());  // discovers all registered agents

const httpServer = createServer(app);
const io = new Server(httpServer);
createAgentGateway({ io });  // discovers all registered agents

httpServer.listen(3000);
You can still pass agents explicitly if you prefer: 
app.use("/api", createAgentRouter({ agents: { assistant: agent } }));
createAgentGateway({ io, agents: { assistant: agent } });

​
REST Endpoints

MethodPathDescription
POST/agents/:name/runRun agent, return full response
POST/agents/:name/streamStream agent via SSE
POST/teams/:name/runRun team
POST/teams/:name/streamStream team via SSE
POST/workflows/:name/runRun workflow
GET/agentsList registered agents with metadata
GET/teamsList registered teams
GET/workflowsList registered workflows
GET/registryList all registered entity names
GET/toolsList available tools (when toolkits configured)
GET/tools/:nameGet single tool detail
GET/docsSwagger UI (if enabled)
GET/docs/spec.jsonOpenAPI spec (if enabled)

​
Socket.IO Events

EventDirectionDescription
agent.runClient → ServerTrigger agent run with { name, input, sessionId?, apiKey? }
team.runClient → ServerTrigger team run
agents.listClient → ServerList agents with metadata (acknowledgement callback)
teams.listClient → ServerList teams (acknowledgement callback)
workflows.listClient → ServerList workflows (acknowledgement callback)
registry.listClient → ServerList all registered names (acknowledgement callback)
tools.listClient → ServerList available tools (acknowledgement callback)
tools.getClient → ServerGet single tool detail (acknowledgement callback)
agent.chunkServer → ClientStreamed text chunk
agent.tool.callServer → ClientTool call started
agent.tool.doneServer → ClientTool call finished
agent.doneServer → ClientRun complete with output
agent.errorServer → ClientError occurred

​
Features

Agents, teams, and workflows auto-register into a global Registry when created. Transport layers discover them at request time — entities created after server start are immediately available. Set registry: false to disable and only serve explicitly passed entities.
Enable fileUpload in router options to accept multipart form data. Files are converted to multi-modal content parts (images, audio, documents) and passed to agents.
Clients can pass API keys via headers (x-openai-api-key, x-google-api-key, x-anthropic-api-key, x-api-key) or in the request body.
Enable swagger.enabled to serve interactive API docs at /docs and the OpenAPI spec at /docs/spec.json.
Pass toolkits or toolLibrary in router/gateway options to expose GET /tools and tools.list endpoints. The UI can discover available tools before creating agents.

​
Next Steps