GuidesAdapters

Adapters overview

Bridges between your agent framework and the Astro runtime
View as Markdown

Adapters are the bridge between your agent code and the Astro runtime. They handle the gRPC streaming loop with the messaging sidecar, translate framework-specific events into the messaging protocol (status updates, content chunks, audio, feedback), and let you keep using whatever framework you already chose. You write serve(myAgent); the adapter handles the rest.

Available adapters

PackageLanguageWrapsUse when
@astropods/adapter-mastraTypeScriptMastra AgentYou’re building with Mastra.
astropods-adapter-langchainPythonLangChain / LangGraphYou’re using create_agent / create_react_agent.
@astropods/adapter-coreTypeScriptAnythingCustom Node adapter for a framework not yet supported.
astropods-adapter-corePythonAnythingCustom Python adapter for a framework not yet supported.

The *-core packages contain the framework-agnostic AgentAdapter interface, the MessagingBridge that drives the gRPC streaming loop, and a serve() entry point. The framework adapters (-mastra, -langchain) are thin wrappers that translate framework-specific stream events (Mastra fullStream chunks, LangChain astream updates) into the shared StreamHooks lifecycle.

When to use what

ScenarioPick
Mastra agent (Node/TypeScript)@astropods/adapter-mastra
LangChain or LangGraph agent (Python)astropods-adapter-langchain
Different framework, but Node-based@astropods/adapter-core — implement AgentAdapter
Different framework, but Python-basedastropods-adapter-core — implement AgentAdapter
No framework — calling LLM APIs directly*-core. Treat the LLM stream as your fullStream.
Talking to the messaging service from a non-agent (admin, batch)Skip the adapter and use the Messaging SDK directly.

How they fit together

The boundary between adapter-core and the messaging sidecar is the Messaging SDK gRPC stream. You only touch the SDK directly when you write a custom adapter or skip the adapter layer entirely.

What an adapter handles for you

  • Connecting to the messaging sidecar with automatic reconnect.
  • Announcing your agent’s name, system prompt, and tools so they appear in the playground.
  • Streaming each user message into your code and streaming each chunk of the reply back.
  • Receiving feedback (thumbs up/down, free-form text, button clicks) and routing it to your handler.
  • Handling audio messages — STT before your agent runs, optional TTS on the reply.
  • Tracing — when an OTEL endpoint is set, the framework adapters auto-wire it.

Environment

All adapters share the same environment contract:

VariableDefaultNotes
GRPC_SERVER_ADDRlocalhost:9090Messaging sidecar address. ast dev injects this automatically.
OTEL_EXPORTER_OTLP_ENDPOINTunsetWhen set, the framework adapter wires OTEL tracing automatically.
DEBUGunsetWhen set, adapter-core logs at debug level.

Local development with ast dev injects GRPC_SERVER_ADDR so the same serve(agent) call works both locally and in production.