Custom Agent Logic

Relevant source files

The following files were used as context for generating this wiki page:

• src/agent/custom_agent.py
• src/agent/custom_prompts.py
• src/agent/custom_message_manager.py
• src/agent/custom_views.py
• src/utils/deep_research.py
• webui.py

The Custom Agent Logic is an extension of the base browser-use framework, designed to provide enhanced control, sophisticated state management, and specialized prompting for AI-driven web navigation. It introduces a CustomAgent that incorporates a structured "brain" for self-evaluation, future planning, and long-term memory management during multi-step browser tasks.

This system is central to the project's ability to handle complex user instructions by breaking them down into logical plans, executing sequences of browser actions, and maintaining a persistent memory of extracted information across sessions. It specifically integrates with specialized models like DeepSeek-R1 to leverage "deep thinking" capabilities for research and reasoning.

Sources: src/agent/custom_agent.py:72-135, webui.py:277-310

Core Architecture

The architecture revolves around the CustomAgent class, which inherits from the base Agent service but overrides key methods to implement a custom reasoning loop. The agent utilizes a specialized CustomMessageManager to handle token-efficient conversation history and CustomSystemPrompt to enforce a rigorous JSON response format.

Component Relationship

The following diagram illustrates how the custom agent components interact during a single execution step.

The diagram shows the modular structure of the Custom Agent, highlighting the separation between message management, prompt engineering, and the core reasoning loop.
Sources: src/agent/custom_agent.py:72-160, src/agent/custom_message_manager.py:38-55

State Management and "The Brain"

A key differentiator in the custom logic is the CustomAgentBrain, which structures the AI's internal state into specific fields. This allows the agent to reflect on previous failures and plan future steps explicitly.

Brain Data Structure

Field	Type	Description
prev_action_evaluation	string	Self-analysis of whether the last action achieved its goal (Success/Failed/Unknown).
important_contents	string	Relevant data extracted from the current page to be stored in memory.
task_progress	string	A summary of completed sub-tasks based on history.
future_plans	string	A concise list of remaining steps needed to fulfill the user request.
thought	string	The agent's reasoning process and reflection on failures.
summary	string	A natural language description of the next intended operation.

Sources: src/agent/custom_views.py:24-34, src/agent/custom_prompts.py:22-30

Execution Flow

The CustomAgent.step() method defines the operational cycle. Unlike standard agents, it includes an optional planning phase and sophisticated error handling that removes failed state messages from history to prevent token bloat.

Step-by-Step Sequence

This sequence diagram details the interaction between the agent, the browser context, and the language model during a single navigation step.
Sources: src/agent/custom_agent.py:269-325, src/agent/custom_message_manager.py:70-84

Specialized Prompting

The CustomSystemPrompt enforces strict rules on the model's output to ensure it remains compatible with the custom parsing logic.

• JSON Enforcement: The model must always respond with valid JSON containing the current_state (Brain) and action sequence.
• Action Sequencing: The agent can specify multiple actions (e.g., form filling followed by clicking) in a single step, up to a configurable max_actions_per_step.
• Deep Research Integration: When research is required, the prompt directs the agent to use extract_content to store markdown data rather than just viewing pages.

Sources: src/agent/custom_prompts.py:16-105, src/utils/deep_research.py:130-145

Deep Research and Iterative Search

The deep_research utility leverages CustomAgent in a loop to perform exhaustive information gathering.

1. Search Iteration: The system generates a research plan and multiple search queries.
2. Parallel Agents: It initializes multiple CustomAgent instances (or one persistent one if using a local browser) to execute these queries.
3. Information Recording: An "Expert Information Recorder" processes the search results to update a cumulative JSON record, avoiding redundancy.
4. Final Report: A "Deep Researcher" writer generates a publication-ready Markdown report with citations.

Sources: src/utils/deep_research.py:41-110, src/utils/deep_research.py:230-260

Model-Specific Logic: DeepSeek-R1

The logic includes explicit handling for reasoning models like deepseek-reasoner or deepseek-r1. When these models are detected, the agent:

• Disables standard function calling (as these models primarily use reasoning tags).
• Adjusts the max_input_tokens to 64,000.
• Extracts and logs reasoning_content (the "Thought" chain) before parsing the final JSON output.

Sources: src/agent/custom_agent.py:121-128, src/agent/custom_agent.py:210-215

Conclusion

The Custom Agent Logic transforms a standard browser automation tool into a resilient research and navigation system. By structuring the AI's internal reasoning into a "Brain" and implementing strict message management, it enables stable, multi-step operations and high-quality report generation through the Deep Research module.