External Agents

Agentium’s runtime (registry, Express/Socket.IO gateways, queue workers, observability) is framework-agnostic. Anything that satisfies the ServableAgent contract can be registered and served — the first-party Agent class is just one implementation.

The ServableAgent contract

interface ServableAgent {
  readonly kind: "agent";
  readonly name: string;
  run(input: MessageContent, opts?: RunOpts): Promise<RunOutput>;
  stream(input: MessageContent, opts?: RunOpts): AsyncIterable<StreamChunk>;

  // Optional — each field lights up extra runtime features when present:
  readonly eventBus?: EventBus;          // tracing, metrics, approval streams
  readonly modelId?: string;
  readonly providerId?: string;          // provider-specific API key routing
  readonly tools?: ReadonlyArray<{ name: string; description?: string }>;
  readonly instructions?: unknown;       // swagger docs, agent cards
  readonly hasStructuredOutput?: boolean;
  readonly structuredOutputSchema?: unknown;
  readonly memory?: unknown;             // enables the corrections endpoint
  readonly approvalManager?: unknown;    // enables HITL approval endpoints
  readonly checkpointManager?: unknown;  // enables checkpoint endpoints
}

defineExternalAgent()

Wrap external logic behind an explicit host function. It normalizes your return value into a full RunOutput, provides a default stream() fallback, wires up an EventBus (so observability works out of the box), and auto-registers in the global registry.

import { defineExternalAgent, type MessageContent } from "@agentium/core";

// The host adapts its framework's output to a string at this boundary.
export function createResearcher(invoke: (input: MessageContent) => Promise<string>) {
  return defineExternalAgent({ name: "researcher", register: false, run: invoke });
}

The host still mounts a router or gateway, supplies verified identity, and closes resources owned by its external framework. defineExternalAgent alone does not start a server.

Returning rich output

Return a partial RunOutput to include usage, tool calls, or structured data — missing fields are filled with defaults:

const agent = defineExternalAgent({
  name: "extractor",
  run: async (input) => ({
    text: extracted.summary,
    structured: extracted,
    usage: { promptTokens: 800, completionTokens: 200, totalTokens: 1000 },
  }),
});

Native streaming

By default, stream() runs to completion and yields the text as a single chunk. Provide your own generator for true streaming:

const agent = defineExternalAgent({
  name: "streamer",
  run: async (input) => fullResponse(input),
  stream: async function* (input) {
    for await (const token of llm.streamTokens(input)) {
      yield { type: "text", text: token };
    }
    yield { type: "finish", finishReason: "stop" };
  },
});

Configuration

Property	Type	Required	Default	What it controls
`name`	`string`	Yes	—	Registry key and route path (`/agents/:name/...`)
`run`	`(input, opts) => Promise<string \| Partial<RunOutput>>`	Yes	—	The agent’s logic
`stream`	`(input, opts) => AsyncIterable<StreamChunk>`	No	run-then-yield fallback	Native streaming
`instructions`	`string`	No	—	Shown in registry descriptions and swagger
`modelId` / `providerId`	`string`	No	—	Metadata for discovery cards and API key routing
`register`	`boolean`	No	`true`	Auto-register in the global registry
`eventBus`	`EventBus`	No	fresh instance	Bring your own bus for shared observability

Observe the run lifecycle

defineExternalAgent emits the standard run lifecycle events (run.start, run.complete, run.error) on its event bus, so Tracer, MetricsExporter, and StructuredLogger work unchanged:

import { defineExternalAgent, EventBus, type MessageContent } from "@agentium/core";
import { instrumentBus } from "@agentium/observability";

export async function observeResearch(run: (input: MessageContent) => Promise<string>, input: string) {
  const eventBus = new EventBus();
  const agent = defineExternalAgent({ name: "researcher", register: false, eventBus, run });
  const observation = instrumentBus(eventBus, { exporters: ["console"], metrics: true });
  try { return await agent.run(input); }
  finally { await observation.shutdown(); }
}

Registry names are labels (v2.3.2+)

Registering an agent with an existing name replaces the previous entry (last-write-wins) — names are labels, not unique keys. Gateways resolve a name to the most recently registered instance. Use register: false for request-owned instances so they cannot replace a shared hosted service.

import { Agent, type ModelProvider } from "@agentium/core";

export async function classify(model: ModelProvider, email: string) {
  const agent = new Agent({ name: "email-classifier", model, register: false });
  try { return await agent.run(email); }
  finally { await agent.close(); }
}

Pass register: false (on AgentConfig or ExternalAgentConfig) for ephemeral agents that should skip the registry entirely.

Cross-references

Express Transport — the routes every served agent gets
Socket.IO Gateway — realtime serving
Observability — event-bus-driven tracing and metrics

Build

Agent applications

Harness runtime

Teams and workflows

Data and capabilities

Interfaces and jobs

Voice and telephony

Verify and manage

The ServableAgent contract

defineExternalAgent()

Returning rich output

Native streaming

Configuration

Observe the run lifecycle

Registry names are labels (v2.3.2+)

Cross-references

​The ServableAgent contract

​defineExternalAgent()

​Returning rich output

​Native streaming

​Configuration

​Observe the run lifecycle

​Registry names are labels (v2.3.2+)

​Cross-references

The ServableAgent contract

defineExternalAgent()

Returning rich output

Native streaming

Configuration

Observe the run lifecycle

Registry names are labels (v2.3.2+)

Cross-references