High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
OpenPoke is an open-source assistant architecture designed to mirror a multi-agent orchestration stack. It is built using a decoupled approach consisting of a Next.js frontend, a FastAPI backend, and a dual-agent system that separates user interaction from task execution. The system leverages OpenRouter for LLM capabilities and Composio for third-party tool integrations like Gmail.
Sources: README.md:3-12
System Overview
The architecture is divided into three primary layers: the Web UI, the Interaction Layer, and the Execution Layer. This separation ensures that the persona and conversational state are handled independently of the technical complexities of tool invocation and API management.
Component Stack
| Layer | Technology | Key Responsibility |
|---|---|---|
| Frontend | Next.js (React) | User interface, chat history rendering, and API proxying. |
| Backend | FastAPI (Python) | Agent orchestration, conversation logging, and service management. |
| LLM Gateway | OpenRouter | Unified API access to various LLM models for agents. |
| Tooling | Composio | Managed authentication and execution for Gmail and Google Contacts. |
Sources: README.md:15-30, web/package.json:11-15
Core Agent Orchestration
OpenPoke utilizes a "Interaction/Execution split" where two distinct types of agents collaborate to fulfill user requests.
1. Interaction Agent
The Interaction Agent acts as the primary interface for the user. It manages the conversational tone, maintains a summary of the working memory, and delegates complex tasks to Execution Agents. It does not perform technical tasks itself but uses the send_message_to_agent tool to command the execution layer.
Sources: server/agents/interaction_agent/runtime.py:48-75, server/agents/interaction_agent/system_prompt.md:16-25
2. Execution Agent
The Execution Agent is the "engine" of the system. It receives instructions from the Interaction Agent and uses specialized tools (e.g., Gmail, Search) to perform actions. It reports results back to the Interaction Agent for final presentation to the user.
Sources: server/agents/execution_agent/runtime.py:38-50, server/agents/execution_agent/system_prompt.md:3-10
Multi-Agent Interaction Flow
The following diagram illustrates how a user request flows through the system from the UI to the execution tools.
A brief diagram showing the request flow from the user through the interaction and execution agents back to the UI.
Sources: server/agents/interaction_agent/runtime.py:115-160, web/app/api/chat/route.ts:35-55
Conversation Management and Memory
OpenPoke maintains persistence through a structured logging system and an automated summarization service. This allows agents to retain context over long-running sessions.
Logging and Persistence
Every message exchange is recorded in poke_conversation.log using XML-like tags (e.g., <user_message>, <agent_message>, <poke_reply>). These logs serve as the primary source of truth for conversation history.
Sources: server/services/conversation/log.py:53-70, server/services/conversation/log.py:126-145
Summarization Service
To manage token limits and provide high-level context, the system includes a background summarizer. It monitors the conversation length and triggers an LLM call to compress older logs into a "Working Memory" summary when a configurable threshold is reached.
Sources: server/services/conversation/summarization/summarizer.py:75-120
This sequence diagram shows the internal backend process for persisting messages and triggering the summarization logic.
Sources: server/services/conversation/log.py:147-175, server/services/conversation/summarization/summarizer.py:82-95
Data Flow and API Integration
The system uses a tiered request structure to handle communications between the frontend and backend.
Frontend-Backend Proxy
The Next.js frontend includes an API route that proxies chat requests to the Python FastAPI server. This ensures that sensitive environment variables (like API keys) are kept server-side while providing a clean endpoint for the React components.
| Endpoint | Method | Source | Description |
|---|---|---|---|
/api/chat | POST | web/app/api/chat/route.ts | Proxies user messages to the Python backend. |
/api/chat/history | GET | web/app/api/chat/history/route.ts | Fetches the full conversation transcript. |
/api/chat/history | DELETE | web/app/api/chat/history/route.ts | Triggers a clear of the local log files. |
Sources: web/app/api/chat/route.ts:24-55, web/app/api/chat/history/route.ts:4-28
LLM Interface
The request_chat_completion utility is used by both agents and the summarizer to interact with OpenRouter. It supports standard messaging payloads as well as tool definitions (schemas) for agent function calling.
Sources: server/agents/interaction_agent/runtime.py:175-188, server/agents/execution_agent/runtime.py:143-154
Summary
The High-Level Architecture of OpenPoke is centered on a strict separation of concerns between conversational persona and task execution. By utilizing an Interaction/Execution agent split supported by a robust logging and summarization layer, the system maintains persistent context while safely executing complex third-party integrations via a centralized tool registry.