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
}

import { defineExternalAgent } from "@agentium/core";

const researcher = defineExternalAgent({
  name: "researcher",
  run: async (input) => {
    // Wrap a LangGraph graph, a Claude Agent SDK call, or any custom code
    const result = await graph.invoke({ messages: [String(input)] });
    return result.messages.at(-1).content;   // plain string is fine
  },
});

// Immediately servable:
//   POST /agents/researcher/run
//   POST /agents/researcher/stream

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

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" };
  },
});

import { instrumentBus } from "@agentium/observability";

const agent = defineExternalAgent({ name: "researcher", run });
instrumentBus(agent.eventBus!, { tracing: true, metrics: true });

// Safe to call per-request — no name collision errors
function classify(email: string) {
  const agent = new Agent({ name: "email-classifier", model: getModel(), ... });
  return agent.run(email);
}