Execution Agent
Relevant source files
The following files were used as context for generating this wiki page:
The Execution Agent serves as the "execution engine" of the OpenPoke system. Its primary purpose is to accomplish specific goals and tasks assigned by the Interaction Agent, such as managing emails, creating drafts, or setting reminders. Unlike the Interaction Agent, the Execution Agent does not have direct access to the user; instead, it provides structured contextual information and results back to the Interaction Agent, which then handles the user-facing conversation.
Sources: server/agents/execution_agent/system_prompt.md:1-12, README.md:10-15
Architecture and Components
The Execution Agent system is composed of several specialized modules that handle state management, LLM orchestration, batch processing, and persistent logging.
Execution Agent Core
The ExecutionAgent class manages the state and history of a specific agent instance. It is responsible for building the system prompt, incorporating conversation history from the log store, and recording final responses and tool executions.
Sources: server/agents/execution_agent/agent.py:35-45
Execution Runtime
The ExecutionAgentRuntime manages the lifecycle of a single request. It handles the iterative loop with the Large Language Model (LLM) via OpenRouter, extracting tool calls, executing them, and feeding the results back into the model context until a final response is generated.
Sources: server/agents/execution_agent/runtime.py:30-45
Batch Management
The ExecutionBatchManager coordinates multiple execution agents simultaneously. It batches results from different agents that might be running in parallel and dispatches a combined outcome to the Interaction Agent. This ensures that the Interaction Agent can present a unified update to the user even if multiple background tasks were triggered.
Sources: server/agents/execution_agent/batch_manager.py:41-45, server/agents/interaction_agent/tools.py:112-125
Data Flow Overview
The following diagram illustrates the flow of a task from the Interaction Agent through the Execution Agent's runtime and back.
Task Execution Logic
The agent operates in a loop, processing instructions through a series of "thoughts" and "actions" (tool calls).
- Instruction Reception: Receives instructions and loads relevant history (truncated by
conversation_limitif necessary). - LLM Iteration: The runtime enters a loop (up to 8 iterations). It calls the LLM with the current message stack and available tool schemas.
- Tool Processing: If the LLM requests tool calls, the runtime parses the JSON arguments, executes the corresponding function from the registry, and appends the result to the conversation.
- Logging: Every action and tool response is recorded in the
ExecutionAgentLogStore. - Finalization: Once the LLM provides a content-only response without tool calls, the execution is considered complete.
| Component | Responsibility |
|---|---|
MAX_TOOL_ITERATIONS | Limits the agent to 8 tool calls per request to prevent infinite loops. |
ExecutionResult | Dataclass containing success status, response text, and list of tools executed. |
_extract_tool_calls | Parses raw LLM response into structured tool names and arguments. |
Sources: server/agents/execution_agent/runtime.py:32-35, server/agents/execution_agent/runtime.py:55-120, server/agents/execution_agent/agent.py:73-100
Tooling and Integrations
Execution Agents have access to a suite of tools, primarily focused on Gmail integration via Composio.
Gmail Tools
The system includes specialized functions for:
gmail_create_draft: Creates an email draft. The system prompt mandates that the agent never send an email directly without first creating a draft for user review.gmail_execute_draft: Sends a previously approved draft.gmail_forward_emailandgmail_reply_to_thread: Handles thread-based communication.gmail_search_peopleandgmail_get_contacts: Accesses user contact information.
Sources: server/agents/execution_agent/tools/gmail.py:27-160, server/agents/execution_agent/system_prompt.md:5-7
Trigger and Reminder Tools
Agents can manage temporal triggers using the createTrigger, updateTrigger, and listTriggers tools, which utilize ISO 8601 timestamps and iCalendar RRULE strings for recurrence.
Sources: server/agents/execution_agent/system_prompt.md:43-55
Logging and Persistence
The ExecutionAgentLogStore maintains an append-only journal for every agent using XML-style tags. This transcript is used to provide the agent with long-term memory and context of its previous actions.
Log entries include a timestamp and an encoded payload. The log store uses file-based locking (threading.Lock) to ensure thread safety during concurrent writes to different agent logs.
Sources: server/services/execution/log_store.py:48-90, server/services/execution/log_store.py:118-135
Configuration
The Execution Agent's behavior is governed by environment variables and system prompt constraints.
| Variable/Constraint | Description | Source |
|---|---|---|
OPENROUTER_API_KEY | Required for LLM connectivity. | runtime.py:44 |
execution_agent_model | Specifies the LLM model used for execution tasks. | runtime.py:39 |
| Draft Enforcement | Agents must create drafts rather than sending emails directly. | system_prompt.md:6 |
| Parallelism | Interaction agent is encouraged to call multiple execution agents in parallel. | interaction_agent/system_prompt.md:12 |
Sources: server/agents/execution_agent/runtime.py:38-45, server/agents/execution_agent/system_prompt.md:5-10
The Execution Agent provides a robust, logged, and tool-enabled environment for background task fulfillment, abstracting complex operations like email management and scheduling away from the primary conversational logic.