Skip to main content

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:

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. Registry names are labels, not unique keys (v2.3.2+): registering an agent with an existing name replaces the previous entry (last-write-wins), so the same agent definition can be constructed repeatedly — loops, factories, concurrent requests — without Duplicate agent name errors. Routes resolve a name to the most recently registered instance.
You can still pass agents explicitly if you prefer:

REST Endpoints


Socket.IO Events


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