Introduction to OpenPoke
Relevant source files
The following files were used as context for generating this wiki page:
OpenPoke is an open-source, multi-agent orchestration stack designed to provide a useful AI assistant experience. It is a simplified implementation of Interaction Company's Poke assistant, focusing on core functionalities such as email triage, reminders, and persistent agent interactions. The project demonstrates how a split between interaction and execution agents can manage complex workflows while remaining easy to deploy locally.
Sources: README.md:1-12
System Architecture
The project follows a decoupled architecture consisting of a FastAPI backend and a Next.js frontend. The backend implements a multi-agent system powered by OpenRouter, utilizing a specific "interaction/execution split" to handle user requests and task performance.
Core Components
- Interaction Agent: Acts as the user-facing interface. It handles natural language understanding, maintains persona, and orchestrates task delegation.
- Execution Agents: Task-specific engines that lack direct user access. They perform technical operations like Gmail management or reminder scheduling.
- Gmail Tooling: Integrated via Composio to enable email drafting, replying, and forwarding directly within the chat interface.
- Working Memory & Logging: A persistence layer that logs conversation history and generates summaries to maintain context across sessions.
Sources: README.md:5-15, server/agents/interaction_agent/runtime.py:23-45, server/agents/execution_agent/system_prompt.md:1-10
High-Level Data Flow
The following diagram illustrates how a user request flows from the web interface through the agent orchestration layers.
This flow ensures that the user only interacts with the warm, witty persona of the Interaction Agent while technical "heavy lifting" is isolated in execution environments.
Sources: web/app/api/chat/route.ts:25-50, server/agents/interaction_agent/runtime.py:53-75, server/agents/interaction_agent/tools.py:115-135
Agent Orchestration
The system relies on a two-tier agent model to separate communication from technical execution.
Interaction Agent
The Interaction Agent serves as the "Chief-of-Staff." Its primary tool is send_message_to_agent, which it uses to delegate tasks. It is responsible for:
- Summarizing execution results for the user.
- Maintaining a consistent personality (witty, warm, terse).
- Obtaining user confirmation before performing destructive or external actions (e.g., sending emails).
Sources: server/agents/interaction_agent/system_prompt.md:12-40, server/agents/interaction_agent/runtime.py:48-90
Execution Agent
Execution agents act as the "execution engine." They are instructed to think step-by-step and use specific tools to fulfill goals defined by the Interaction Agent. They communicate results back to the Interaction Agent in a raw, data-centric format.
Sources: server/agents/execution_agent/system_prompt.md:1-15, server/agents/execution_agent/tools/gmail.py:240-260
Interaction Loop logic
The Interaction Agent manages an iterative loop to process tool calls until a final user response is ready.
| Feature | Description |
|---|---|
| Max Iterations | The loop runs for a maximum of 8 iterations to prevent infinite tool calling. |
| Parallelism | The agent is instructed to split complicated tasks into concurrent calls when possible. |
| Tool Execution | Tools like send_message_to_agent and send_draft are handled via the handle_tool_call function. |
Sources: server/agents/interaction_agent/runtime.py:47, server/agents/interaction_agent/system_prompt.md:20-25, server/agents/interaction_agent/tools.py:185-210
Memory and Persistence
OpenPoke uses a structured logging system to maintain long-term context and "Working Memory."
Conversation Logging
Every message is tagged and recorded in poke_conversation.log. Tags include <user_message>, <agent_message>, <poke_reply>, and <wait>.
| Tag | Purpose |
|---|---|
user_message | Input directly from the human user. |
agent_message | Technical status updates from execution agents. |
poke_reply | The Interaction Agent's response to the user. |
wait | Orchestration metadata to prevent duplicate responses. |
Sources: server/services/conversation/log.py:110-150, server/agents/interaction_agent/system_prompt.md:63-75
Summarization Logic
To stay within LLM context limits, the system triggers a summarization process when a threshold of new entries is reached.
The summarizer produces a "working-memory briefing" containing timelines, commitments, pending follow-ups, and user preferences.
Sources: server/services/conversation/summarization/summarizer.py:80-120, server/services/conversation/summarization/prompt_builder.py:20-50
Technical Setup and Requirements
The project requires a split environment to run both the FastAPI server and the Next.js frontend.
| Requirement | Version / Detail |
|---|---|
| Python | 3.10+ |
| Node.js | 18+ |
| OpenRouter API Key | Required for LLM orchestration. |
| Composio API Key | Required for Gmail integrations. |
| Environment File | .env containing keys and local server URLs. |
Sources: README.md:14-40
Project Structure
server/: FastAPI application, agents, and tool definitions.web/: Next.js application and UI components.server/data/: Local storage for conversation logs and runtime state.
Sources: README.md:95-100
Summary
OpenPoke provides a template for building sophisticated AI assistants by separating the "brain" (Interaction Agent) from the "hands" (Execution Agents). By leveraging OpenRouter for model flexibility and Composio for specialized tool access, it creates a persistent, context-aware environment for managing personal workflows such as email and reminders.
Sources: README.md:1-10, server/agents/interaction_agent/runtime.py:10-30