Custom adapter (Node)

@astropods/adapter-core is the framework-agnostic core. Implement the AgentAdapter interface, hand it to serve(), and the bundled MessagingBridge handles the gRPC streaming loop, audio, feedback, reconnect, and shutdown.

Use this when there’s no first-party adapter for your framework (or no framework at all — you’re calling LLM APIs directly).

Install

$
bun add @astropods/adapter-core @astropods/messaging
$
# or: npm install @astropods/adapter-core @astropods/messaging

Minimal adapter

1
import { serve } from '@astropods/adapter-core';
2
import type { AgentAdapter } from '@astropods/adapter-core';
3
4
const adapter: AgentAdapter = {
5
  name: 'My Agent',
6
7
  async stream(prompt, hooks, options) {
8
    try {
9
      hooks.onChunk('Hello, ');
10
      hooks.onChunk(`${prompt}!`);
11
      hooks.onFinish();
12
    } catch (err) {
13
      hooks.onError(err as Error);
14
    }
15
  },
16
17
  getConfig() {
18
    return { systemPrompt: 'You are a helpful assistant.', tools: [] };
19
  },
20
};
21
22
serve(adapter);

serve(adapter) connects to localhost:9090 (or GRPC_SERVER_ADDR) and runs until the process exits.

Lifecycle

AgentAdapter

StreamHooks

Call these from inside stream() and streamAudio(). They translate directly into outbound AgentResponse messages on the gRPC stream.

StatusUpdate.status values: THINKING, SEARCHING, GENERATING, PROCESSING, ANALYZING, CUSTOM. Use CUSTOM with customMessage.

StreamOptions

The bridge passes this to every stream() / streamAudio() call.

AudioInput

Passed to streamAudio().

FeedbackEvent

Passed to onFeedback(). kind is a stable string discriminator so you don’t have to import proto types to switch on it.

FeedbackEvent.kind values

onFeedback() may return void or a Promise. The bridge does not await the result — so don’t block the stream on slow I/O. Push to a queue or trigger an async write and return.

Trace context

Call hooks.onTraceContext({ traceparent }) once per turn to attach the turn’s W3C trace context. The bridge stamps it on every AgentResponse it emits for the turn, so a consumer can correlate any response — and the feedback that references it — back to the trace. It’s ignored when traceparent is empty.

createTraceparent(input) formats a native trace/span ID pair into a W3C traceparent string. It returns "" for invalid or all-zero IDs, so it’s safe to pass raw OpenTelemetry span context. traceFlags accepts a number or hex string and defaults to 01 (sampled).

1
import { createTraceparent } from '@astropods/adapter-core';
2
3
const { traceId, spanId, traceFlags } = span.spanContext();
4
hooks.onTraceContext?.({ traceparent: createTraceparent({ traceId, spanId, traceFlags }) });

The first-party framework adapters already emit trace context from their root span — you only wire this up in a custom adapter. See the Messaging SDK for the underlying TraceContext wire shape.

serve(adapter, options?)

Thin wrapper around MessagingBridge that handles process lifecycle.

ServeOptions.serverAddress defaults to process.env.GRPC_SERVER_ADDR || 'localhost:9090'.

Worked example: a plain OpenAI agent

No framework — just calling OpenAI’s streaming chat API and forwarding tokens.

1
import OpenAI from 'openai';
2
import { serve } from '@astropods/adapter-core';
3
import type { AgentAdapter } from '@astropods/adapter-core';
4
5
const openai = new OpenAI({
6
  apiKey: process.env.ASTRO_GATEWAY_API_KEY,
7
  baseURL: process.env.ASTRO_GATEWAY_URL,
8
});
9
10
const adapter: AgentAdapter = {
11
  name: 'OpenAI Direct',
12
13
  async stream(prompt, hooks, options) {
14
    try {
15
      hooks.onStatusUpdate({ status: 'GENERATING' });
16
17
      const stream = await openai.chat.completions.create({
18
        model: 'claude-sonnet-4-6',
19
        messages: [
20
          { role: 'system', content: 'You are a helpful assistant.' },
21
          { role: 'user', content: prompt },
22
        ],
23
        stream: true,
24
      });
25
26
      for await (const chunk of stream) {
27
        const text = chunk.choices[0]?.delta?.content;
28
        if (text) hooks.onChunk(text);
29
      }
30
31
      hooks.onFinish();
32
    } catch (err) {
33
      hooks.onError(err as Error);
34
    }
35
  },
36
37
  getConfig() {
38
    return { systemPrompt: 'You are a helpful assistant.', tools: [] };
39
  },
40
41
  onFeedback(event) {
42
    // Push to your evals pipeline, Airtable, etc. Don't block.
43
    void recordFeedback(event);
44
  },
45
};
46
47
serve(adapter);

Rules of thumb

• Call exactly one of onFinish() or onError() per request. Skipping either leaves the user staring at a half-rendered reply.
• Catch your own exceptions inside stream(). If you let the promise reject, the user sees nothing.
• Don’t block in onFeedback() — push to a queue or trigger async work and return.
• Use options.conversationId (not platformContext.threadId) as your memory key.
• Use only options.attachments as file input for the turn. Write output files to AGENT_FILES_DIR and call onFile before onFinish; see Files in chat.
• Set up OTEL manually before calling serve() if you want traces. Framework adapters auto-configure this; the raw core does not.

Re-exported types

1
import type {
2
  AgentAdapter, AudioInput, FeedbackEvent,
3
  StreamHooks, StreamOptions, ServeOptions,
4
  PlatformContext, PlatformContextEventKind,
5
  TraceContext, TraceparentInput,
6
} from '@astropods/adapter-core';
7
8
import { serve, MessagingBridge, logger, createTraceparent } from '@astropods/adapter-core';

logger is a Pino instance. Use it for adapter logs so output stays consistent with the bridge.

See Messaging SDK (Node) for the underlying proto shapes referenced by StreamHooks and PlatformContext.