GuidesAdapters

Adapters overview

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

Adapters connect your agent code to the Astro AI runtime. They translate your framework’s events into the messaging protocol — status updates, content chunks, audio, and feedback — so you keep using whatever framework you already chose. You write serve(myAgent); the adapter handles the rest.

Choose an adapter

PackageLanguageUse when
@astropods/adapter-mastraTypeScriptBuilding with Mastra.
astropods-adapter-langchainPythonUsing LangChain or LangGraph (create_agent / create_react_agent).
@astropods/adapter-coreTypeScriptA Node framework without a dedicated adapter, or calling LLM APIs directly. Implement AgentAdapter.
astropods-adapter-corePythonA Python framework without a dedicated adapter. Implement AgentAdapter.

When you call LLM APIs directly, treat the LLM stream as your fullStream. To reach Astro AI messaging from a non-agent process (admin or batch), skip the adapter and use the Messaging SDK directly — the same SDK you work with when writing a custom adapter.

The *-core packages contain the framework-agnostic AgentAdapter interface 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.

What an adapter handles for you

  • Connecting to Astro AI messaging 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 service address. ast dev injects this automatically.
AGENT_FILES_DIR/data/filesShared file store for web-chat uploads and agent-produced downloads. See Files in chat.
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.