Relevant source files

The following files were used as context for generating this wiki page: - [server/agents/interaction\_agent/agent.py](https://github.com/RemyLoveLogicAI/openpoke/blob/main/server/agents/interaction_agent/agent.py) - [server/agents/interaction\_agent/tools.py](https://github.com/RemyLoveLogicAI/openpoke/blob/main/server/agents/interaction_agent/tools.py) - [server/agents/interaction\_agent/runtime.py](https://github.com/RemyLoveLogicAI/openpoke/blob/main/server/agents/interaction_agent/runtime.py) - [server/agents/interaction\_agent/system\_prompt.md](https://github.com/RemyLoveLogicAI/openpoke/blob/main/server/agents/interaction_agent/system_prompt.md) - [server/services/conversation/log.py](https://github.com/RemyLoveLogicAI/openpoke/blob/main/server/services/conversation/log.py) - [server/agents/execution\_agent/batch\_manager.py](https://github.com/RemyLoveLogicAI/openpoke/blob/main/server/agents/execution_agent/batch_manager.py)

# Interaction Agent 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](#execution-agent-integration). 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: 1. **Context Assembly:** Loads conversation history and current active agent roster. 2. **LLM Iteration:** Queries the LLM with the context and available tool schemas. 3. **Tool Execution:** If the LLM requests a tool call, the runtime executes it and feeds the result back into the loop. 4. **Finalization:** Once the LLM provides a final text response, the loop terminates and the message is recorded in the conversation log. ```mermaid flowchart TD Start[New Message] --> History[Load History & Roster] History --> LLMCall[Call LLM with Tools] LLMCall --> Dec{Tool Call?} Dec -- Yes --> ToolExec[Execute Tool] ToolExec --> LLMCall Dec -- No --> Record[Record Reply] Record --> Finish[Return to User] ``` 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. * ``: Previous exchanges. * ``: List of currently running execution agents. * ``: The latest input from the user. * ``: 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. ```mermaid sequenceDiagram participant U as User participant IA as Interaction Agent participant T as Tool System participant EB as Execution Batch Manager U->>IA: "Send email to Bob" IA->>T: send_message_to_agent("Email Agent", "Draft email...") T->>EB: execute_agent("Email Agent", ...) EB-->>T: Submitted T-->>IA: ToolResult(Success) IA->>U: "I'm drafting that email for you now." ``` 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: 1. The Interaction Agent calls `send_message_to_agent`. 2. The `ExecutionBatchManager` manages the lifecycle of the specialized agent. 3. 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. ```python # 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}\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 `wait` tool 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.