Interaction Agent
Relevant source files
The following files were used as context for generating this wiki page:
The Interaction Agent serves as the primary user-facing orchestrator within the OpenPoke ecosystem. Its main responsibility is to manage natural language conversations with the user while delegating technical or background tasks to specialized Execution Agents. It acts as a "witty and warm" personal assistant that maintains persona consistency and coordinates multi-agent workflows.
The agent operates using an iterative interaction loop powered by Large Language Models (LLMs) via OpenRouter. It interprets user intent, calls appropriate tools, manages conversation history, and summarizes results from background tasks to present them to the user in a human-friendly format.
Sources: server/agents/interaction_agent/system_prompt.md:1-20, server/agents/interaction_agent/runtime.py:46-75
Core Architecture
The Interaction Agent architecture is divided into a runtime environment, a toolset, and a prompt construction system. It utilizes a stateful loop to process messages until a final user-facing response is generated.
Execution Workflow
When a message (from a user or an execution agent) is received, the agent follows a structured sequence:
- Context Assembly: Loads conversation history and current active agent roster.
- LLM Iteration: Queries the LLM with the context and available tool schemas.
- Tool Execution: If the LLM requests a tool call, the runtime executes it and feeds the result back into the loop.
- Finalization: Once the LLM provides a final text response, the loop terminates and the message is recorded in the conversation log.
The diagram shows the iterative loop where the agent can call multiple tools (up to 8 iterations) before finalizing a response.
Sources: server/agents/interaction_agent/runtime.py:108-161, server/agents/interaction_agent/agent.py:19-33
Components and Data Structures
InteractionAgentRuntime
This class manages the lifecycle of a single interaction turn. It handles API communication, tool parsing, and error management.
| Attribute | Type | Description |
|---|---|---|
MAX_TOOL_ITERATIONS | int | Limit of 8 iterations to prevent infinite loops. |
conversation_log | ConversationLog | Persistent storage for user and agent messages. |
working_memory_log | WorkingMemoryLog | Access to summarized conversation history. |
tool_schemas | List[Dict] | OpenAI-compatible definitions for agent capabilities. |
Sources: server/agents/interaction_agent/runtime.py:46-63
Message Formatting
Messages are structured using XML-like tags to provide clear boundaries for the LLM.
<conversation_history>: Previous exchanges.<active_agents>: List of currently running execution agents.<new_user_message>: The latest input from the user.<new_agent_message>: Updates from execution agents.
Sources: server/agents/interaction_agent/agent.py:45-66, server/agents/interaction_agent/system_prompt.md:57-75
Tool System
The Interaction Agent uses specialized tools to interact with the system and the user. Unlike execution agents, these tools focus on orchestration and communication.
| Tool Name | Purpose | Key Parameters |
|---|---|---|
send_message_to_agent | Primary tool for task delegation. Reuses existing agents or creates new ones. | agent_name, instructions |
send_message_to_user | Delivers text directly to the user UI. | message |
send_draft | Records an email draft for user review before sending. | to, subject, body |
wait | Adds a silent log entry to prevent redundant responses. | reason |
Sources: server/agents/interaction_agent/tools.py:20-96
Tool Call Sequence
The following sequence diagram illustrates how the Interaction Agent coordinates with an Execution Agent via the tool system.
The diagram illustrates the asynchronous dispatch of tasks to execution agents while the Interaction Agent provides immediate feedback to the user.
Sources: server/agents/interaction_agent/tools.py:102-132, server/agents/execution_agent/batch_manager.py:41-75
Execution Agent Integration
The Interaction Agent relies on Execution Agents for technical tasks like Gmail operations or scheduling. Communication is handled asynchronously:
- The Interaction Agent calls
send_message_to_agent. - The
ExecutionBatchManagermanages the lifecycle of the specialized agent. - Upon completion, results are batched and sent back to the Interaction Agent via
handle_agent_message.
Sources: server/agents/execution_agent/batch_manager.py:118-144, server/agents/interaction_agent/runtime.py:84-106
Persistence and Logging
All interactions are recorded in a structured log file (poke_conversation.log). The ConversationLog class handles reading and writing these entries, which are used to rebuild context for subsequent turns.
# Format used for log storage
def _default_formatter(tag: str, timestamp: str, payload: str) -> str:
encoded = _encode_payload(payload)
return f"<{tag} timestamp=\"{timestamp}\">{encoded}</{tag}>\n"
Sources: server/services/conversation/log.py:34-40, server/services/conversation/log.py:116-130
Persona and Guidelines
The Interaction Agent is governed by a strict system prompt that defines its "Human Texting Voice."
- Tone: Witty, warm, and concise (similar to "Donna" from Suits).
- Adaptiveness: Matches user's texting style (e.g., lowercase, emojis) but only if the user initiates.
- Safety: Must never send emails without showing a draft and receiving user confirmation.
- Redundancy: Must use the
waittool to avoid showing the same information twice.
Sources: server/agents/interaction_agent/system_prompt.md:8-15, server/agents/interaction_agent/system_prompt.md:95-130
Summary
The Interaction Agent is the central intelligence of OpenPoke, bridging the gap between raw execution power and a conversational user interface. By utilizing an iterative loop and a robust tool system, it ensures that complex tasks are delegated correctly while maintaining a consistent, personable relationship with the user.