> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Transport Overview

> Transport layer concept—Express REST API and Socket.IO for exposing Agentium agents, teams, and workflows over HTTP and WebSockets.

# 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

<CardGroup cols={2}>
  <Card title="Express Router" icon="server">
    `createAgentRouter()` returns an Express router with REST endpoints for agents, teams, and workflows.
  </Card>

  <Card title="Socket.IO Gateway" icon="bolt">
    `createAgentGateway()` attaches real-time handlers to a Socket.IO server for streaming agent responses.
  </Card>
</CardGroup>

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:

<CodeGroup>
  ```bash npm theme={null}
  npm install @agentium/transport express socket.io
  ```

  ```bash pnpm theme={null}
  pnpm add @agentium/transport express socket.io
  ```
</CodeGroup>

***

## 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.

```typescript theme={null}
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:

```typescript theme={null}
app.use("/api", createAgentRouter({ agents: { assistant: agent } }));
createAgentGateway({ io, agents: { assistant: agent } });
```

***

## REST Endpoints

| Method | Path                   | Description                                     |
| ------ | ---------------------- | ----------------------------------------------- |
| POST   | `/agents/:name/run`    | Run agent, return full response                 |
| POST   | `/agents/:name/stream` | Stream agent via SSE                            |
| POST   | `/teams/:name/run`     | Run team                                        |
| POST   | `/teams/:name/stream`  | Stream team via SSE                             |
| POST   | `/workflows/:name/run` | Run workflow                                    |
| GET    | `/agents`              | List registered agents with metadata            |
| GET    | `/teams`               | List registered teams                           |
| GET    | `/workflows`           | List registered workflows                       |
| GET    | `/registry`            | List all registered entity names                |
| GET    | `/tools`               | List available tools (when toolkits configured) |
| GET    | `/tools/:name`         | Get single tool detail                          |
| GET    | `/docs`                | Swagger UI (if enabled)                         |
| GET    | `/docs/spec.json`      | OpenAPI spec (if enabled)                       |

***

## Socket.IO Events

| Event             | Direction       | Description                                                   |
| ----------------- | --------------- | ------------------------------------------------------------- |
| `agent.run`       | Client → Server | Trigger agent run with `{ name, input, sessionId?, apiKey? }` |
| `team.run`        | Client → Server | Trigger team run                                              |
| `agents.list`     | Client → Server | List agents with metadata (acknowledgement callback)          |
| `teams.list`      | Client → Server | List teams (acknowledgement callback)                         |
| `workflows.list`  | Client → Server | List workflows (acknowledgement callback)                     |
| `registry.list`   | Client → Server | List all registered names (acknowledgement callback)          |
| `tools.list`      | Client → Server | List available tools (acknowledgement callback)               |
| `tools.get`       | Client → Server | Get single tool detail (acknowledgement callback)             |
| `agent.chunk`     | Server → Client | Streamed text chunk                                           |
| `agent.tool.call` | Server → Client | Tool call started                                             |
| `agent.tool.done` | Server → Client | Tool call finished                                            |
| `agent.done`      | Server → Client | Run complete with output                                      |
| `agent.error`     | Server → Client | Error occurred                                                |

***

## Features

<Accordion title="Auto-Discovery">
  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.
</Accordion>

<Accordion title="File Upload">
  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.
</Accordion>

<Accordion title="Per-Request API Keys">
  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.
</Accordion>

<Accordion title="Swagger UI">
  Enable `swagger.enabled` to serve interactive API docs at `/docs` and the OpenAPI spec at `/docs/spec.json`.
</Accordion>

<Accordion title="Tool Discovery">
  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.
</Accordion>

***

## Next Steps

* [Express Router](/transport/express) — `createAgentRouter`, endpoints, middleware
* [Swagger](/transport/swagger) — OpenAPI spec and Swagger UI
* [File Upload](/transport/file-upload) — Multi-modal inputs via HTTP
* [Socket.IO Gateway](/transport/socketio) — Real-time streaming
* [API Keys](/transport/api-keys) — Per-request key overrides
* [Voice Gateway](/voice/overview) — Real-time voice streaming via Socket.IO (`createVoiceGateway`)