Extending OpenPoke
Relevant source files
The following files were used as context for generating this wiki page:
OpenPoke is designed with a modular multi-agent orchestration stack that mirrors a split between interaction and execution. Extending the system involves adding new capabilities to either the Interaction Agent, which manages the user-facing dialogue and personality, or the Execution Agents, which perform specialized technical tasks such as email management or reminder scheduling.
The architecture relies on a tool-calling pattern where Large Language Models (LLMs) select and execute functions defined in Python. Developers can extend OpenPoke by registering new tools in the agent registries, defining new task-specific sub-agents, or modifying the system prompts that dictate agent behavior.
Sources: README.md, server/agents/interaction_agent/runtime.py:20-40
Multi-Agent Architecture Overview
The system operates using two primary agent types: the Interaction Agent and the Execution Agent. The Interaction Agent acts as the "Chief of Staff," communicating with the user and delegating complex work to Execution Agents via the send_message_to_agent tool.
The diagram shows the communication flow where the Interaction Agent mediates all user contact, while Execution Agents handle backend logic and external integrations.
Sources: server/agents/interaction_agent/system_prompt.md:20-50, server/agents/interaction_agent/tools.py:100-110
Extending Execution Capabilities
Execution Agents are "engines" that perform tasks without direct user access. They are extended by adding new functions to the tool registry and defining their schemas so the LLM knows how to invoke them.
Adding New Tools
To add a new tool to an Execution Agent, you must:
- Define the Logic: Create a Python function that performs the action.
- Define the Schema: Create a JSON schema (OpenAI/OpenRouter compatible) describing the function's parameters.
- Register the Tool: Add the function to the agent's tool registry.
| Component | Description | Source File |
|---|---|---|
get_tool_schemas() | Returns the JSON list of available functions for the LLM. | server/agents/execution_agent/runtime.py:38 |
get_tool_registry() | Maps tool names to their actual Python callable implementations. | server/agents/execution_agent/runtime.py:37 |
ExecutionResult | Dataclass containing the success status and response of a task. | server/agents/execution_agent/runtime.py:15-22 |
Example: Gmail Tool Implementation
Gmail tools use the execute_gmail_tool service to interface with Composio. New Gmail-related extensions are registered in the build_registry function within the Gmail tool module.
def build_registry(agent_name: str) -> Dict[str, Callable[..., Any]]:
return {
"gmail_create_draft": gmail_create_draft,
"gmail_execute_draft": gmail_execute_draft,
# Add new tools here
}
Sources: server/agents/execution_agent/tools/gmail.py:320-335, server/agents/execution_agent/runtime.py:150-165
Task-Specific Orchestration
For complex workflows like email searching, OpenPoke uses "task tools." These are essentially sub-agents within the execution layer that run their own internal LLM loops to refine search queries before returning results.
The sequence diagram illustrates the internal loop of the task_email_search tool, which independently consults the LLM to process and select relevant data.
Sources: server/agents/execution_agent/tasks/search_email/tool.py:90-130, server/agents/execution_agent/tasks/search_email/tool.py:140-180
Extending the Interaction Agent
The Interaction Agent can be extended by modifying its personality in system_prompt.md or by adding tools to its specific runtime. It currently supports tools for messaging users, delegating to agents, and managing silent "wait" states.
Tool Registration for Interaction
Tools for the Interaction Agent are defined in server/agents/interaction_agent/tools.py. Adding a tool here allows the "Chief of Staff" to perform new orchestration actions.
send_message_to_agent: Spawns or reuses an execution agent.send_message_to_user: Records a reply in the conversation log for the UI to display.wait: Adds a<wait>entry to the log to prevent redundant processing without notifying the user.
Sources: server/agents/interaction_agent/tools.py:20-90, server/agents/interaction_agent/runtime.py:130-150
Memory and Summarization Extensions
OpenPoke manages long-term context through a summarization service. This can be extended by modifying the SummaryPrompt in prompt_builder.py to change how the "Chief-of-Staff" memory curator prioritizes information like Routines, Preferences, or Pending tasks.
Summarization Configuration
The summarization logic is governed by thresholds in the system settings.
| Configuration Option | Default/Context | Description |
|---|---|---|
summarization_enabled | Boolean | Enables the background summarization task. |
conversation_summary_threshold | Integer | Number of entries required to trigger a summary. |
conversation_summary_tail_size | Integer | Number of recent messages to keep unsummarized for immediate context. |
Sources: server/services/conversation/summarization/summarizer.py:75-90, server/services/conversation/summarization/prompt_builder.py:15-45
Conclusion
Extending OpenPoke requires a clear understanding of the interaction-execution split. New functionalities are typically implemented as Python tools with corresponding JSON schemas, which are then registered in the appropriate agent's runtime. By leveraging the task-tool pattern and the modular summarization system, developers can build complex, stateful AI workflows while maintaining a warm, consistent user personality.