inbound_queue. Agent Manager consumes that queue, resolves the conversation and character, builds the agent input, invokes the LLM agent with tools and memory, then sends replies back through Communication Manager.
The component is the link between Hiro’s message pipeline and the LLM runtime.
Responsibilities
Queue consumption - Agent Manager runs as a long-lived worker. It waits onCommunicationManager.inbound_queue, processes one prepared UnifiedMessage at a time, and always marks the queue item done.
Conversation resolution - For each message, it maps routing.channel and routing.sender_id to a conversation channel row. That row supplies the memory thread ID, database channel ID, and character ID.
Character and model resolution - It loads the conversation character, builds the effective system prompt, resolves the chat model from character preferences and workspace defaults, and reuses a workspace credential store.
Agent input preparation - It builds a text input from direct text content plus adapter-provided descriptions on non-text content. Audio transcripts and image descriptions enter the LLM here.
Agent execution - It invokes a LangChain or LangGraph agent with Hiro tools, persistent conversation memory, and optional summarization.
Reply delivery - It converts provider output into a Hiro text reply, saves the reply to data.db, and enqueues the reply through Communication Manager.
Voice reply delivery - When the device requests a voice reply and policy allows it, Agent Manager synthesizes speech after the text reply has already been queued, then emits a message.voiced event.
Main components
AgentManager
The worker and per-message orchestrator in runtime/agent_manager.py.
It owns the run loop, agent cache, checkpointer lifecycle, credential store reuse, per-message processing, reply construction, and optional TTS scheduling.
Queue worker
Therun() coroutine opens the LangGraph SQLite checkpointer against workspace.db, creates a workspace CredentialStore, clears the compiled agent cache, then drains CommunicationManager.inbound_queue.
The queue boundary is important. Communication Manager owns message validation, adaptation, transcript events, and inbound persistence. Agent Manager starts only after a message is agent-ready.
Message preparation
Message preparation converts aUnifiedMessage into one agent input string.
| Content source | How it becomes agent input |
|---|---|
| Text content item | Uses the item body directly. |
| Audio content item | Uses metadata.description, produced by the audio adapter. |
| Image content item | Uses metadata.description, produced by the image adapter, prefixed with the content type. |
| Unsupported or failed item | Logged and skipped. |
Thread and character resolver
The resolver usesConversationChannelGetTool with the canonical channel name:
| Value | Purpose |
|---|---|
id | LangGraph thread ID and message-store channel ID. |
character_id | Character profile and model preferences for this conversation. |
Agent runtime factory
Agent Manager compiles the actual LLM runtime from:| Input | Role |
|---|---|
| Character system prompt | Persona and behavior instructions. |
| Resolved chat model | Provider/model/temperature/token configuration. |
| Hiro tool registry | Tool set exposed to the agent. |
| LangGraph checkpointer | Persistent per-thread memory. |
| Memory preferences | Whether to use summarization. |
Memory and summarization
Conversation memory is backed byAsyncSqliteSaver in workspace.db.
When summarization is disabled, Agent Manager uses LangChain’s standard create_agent() with the shared checkpointer. When summarization is enabled and a summarization model is available, it builds the custom graph in summarizing_agent_graph.py.
That graph runs:
Reply pipeline
The reply pipeline normalizes provider-native content into plain text, constructs an outboundUnifiedMessage, saves the reply to the message store, and enqueues it through Communication Manager.
If the LLM call fails, Agent Manager still sends a human-readable fallback reply. If saving the reply fails, delivery still proceeds.
Voice reply pipeline
Voice output is a post-reply side effect. The text reply is queued first. Ifrouting.metadata.request_voice_reply is true and workspace/character voice settings resolve to a usable TTS model, Agent Manager starts a detached TTS task. The task emits message.voiced with base64 audio, MIME type, duration, and a ref_id pointing to the text reply.
Processing flow
Related components
Communication Manager
Communication Manager is Agent Manager’s input and output boundary. It supplies agent-ready messages throughinbound_queue and accepts replies through enqueue_outbound().
Message Adapter Pipeline
The adapter pipeline prepares non-text content before Agent Manager sees it. Agent Manager reads adapter output frommetadata.description.
Character and preferences domain
Characters define the system prompt and optional model preferences. Workspace preferences define default chat, summarization, STT, and TTS behavior.Tool registry
Agent Manager exposes Hiro tools to the LangChain or LangGraph agent. The same tool implementations are shared with CLI and server surfaces.Message store
Inbound persistence happens before Agent Manager through Communication Manager’s post-adapt hooks. Outbound agent replies are saved by Agent Manager after reply construction.See also
Communication Manager
The message router that prepares inbound messages and dispatches replies.
Hiro Server components
How the main server components relate to each other.
Channel Manager
The transport manager that owns channel plugins and WebSocket JSON-RPC.