Agent State Management
Relevant source files
The following files were used as context for generating this wiki page:
Agent State Management in this project encompasses the lifecycle, control signals, and data persistence of autonomous AI agents interacting with web browsers. It coordinates between the user interface, the execution logic of the CustomAgent, and specialized research utilities to ensure tasks are executed sequentially, results are recorded, and agents can be interrupted gracefully.
The system utilizes a combination of global state instances, custom data models for tracking progress, and structured prompt engineering to maintain context across asynchronous steps. This ensures that the agent understands its previous actions, current achievements, and future requirements.
Sources: webui.py:27-31, src/agent/custom_agent.py:112-118
Core State Control Components
The management of an agent's operational status (running, stopping, or idle) is centralized through the AgentState utility. This allows external modules, such as the Gradio web interface, to send interruption signals to long-running asynchronous processes like deep research iterations or multi-step browser interactions.
The AgentState Utility
The AgentState class provides a thread-safe mechanism to request and verify stop signals. This is critical for preventing infinite loops in research tasks and allowing users to halt an agent via the UI.
Sources: webui.py:31, src/utils/deep_research.py:220-222
Global Persistence
In the web interface, global variables are maintained to allow persistent browser sessions. This enables the agent to keep the browser window open between different tasks, preserving the visual and session state of the browser.
| Variable | Type | Description |
|---|---|---|
_global_browser | Browser | The persistent browser instance. |
_global_browser_context | BrowserContext | The specific context (tabs, cookies) being used. |
_global_agent | Agent | The currently active agent instance. |
_global_agent_state | AgentState | The controller for stop/start signals. |
Sources: webui.py:23-31
Agent Step and Progress Tracking
The project uses a structured model to track the internal "thoughts" and progress of the agent at every step. This is handled by the CustomAgentStepInfo and CustomAgentBrain models.
The diagram shows the relationship between the persistent step info and the model's generated brain state.
Sources: src/agent/custom_views.py:9-30
State Update Logic
As the CustomAgent executes, it updates its internal memory and progress markers based on the LLM's output. The update_step_info method processes the CustomAgentOutput to append "important_contents" to the agent's long-term memory and update the visible "task_progress".
Sources: src/agent/custom_agent.py:168-195
Execution and Signal Flow
The following sequence diagram illustrates how a stop request from the UI interacts with the running agent state during a deep research task.
The diagram shows the asynchronous interruption of the research loop via the shared state.
Sources: webui.py:68-75, src/utils/deep_research.py:218-223
Information Recording and Memory
The state is not limited to control signals; it includes the accumulation of data retrieved during execution. This is particularly evident in the deep_research module, which manages "History Queries" and "Previous Search Results" to prevent redundant actions.
Data Model for Recorded Information
Information is stored as a JSON-formatted list of objects containing:
- URL/Title: Source metadata.
- Summary Content: Extracted data and figures.
- Thinking: Reasoning on how the info relates to the user's report.
Sources: src/utils/deep_research.py:117-147
Message Management
The CustomMessageManager handles the state history passed to the LLM. It includes:
- System Prompt: The core instructions.
- Context Message: (Optional) extra user-provided context.
- State Messages: The current browser state, including interactive elements and visual context (screenshots).
Sources: src/agent/custom_message_manager.py:53-65
Prompt-Driven State Representation
The CustomSystemPrompt defines how the agent must perceive and report its state. It enforces a JSON format that requires the agent to analyze its own performance and plan ahead.
| JSON Field | Purpose |
|---|---|
prev_action_evaluation | Self-analysis of whether the last action succeeded. |
important_contents | Extraction of relevant data from the current page. |
task_progress | A summary of what has been accomplished so far. |
future_plans | A list of remaining steps to fulfill the instruction. |
Sources: src/agent/custom_prompts.py:19-28
Conclusion
Agent State Management in this repository is a robust framework that bridges high-level user control with low-level browser interaction. By utilizing structured data models like CustomAgentOutput and centralized signal controllers like AgentState, the system maintains consistency even in complex, multi-iteration research tasks. This architecture allows the agent to "remember" its progress, reflect on failures, and provide a transparent view of its internal state to the user.