How convergence-ai/proxy-lite works
Project Type and Purpose
• Proxy Lite is a mini, lightweight autonomous assistant (a “proxy”) that automates tasks by interacting with web environments. It supports both CLI- and web UI–based usage.
• Its main objective is to process user commands (e.g., “Book a table…”) and autonomously complete tasks (such as web browsing and tool usage) by running a loop between a solver, agent, and environment.
• It uses a modular, pluggable architecture with components for agents, environments, solvers, and tools.
Analyzing the File Structure
• The top-level directories and files include configuration files (.gitignore, Makefile, pyproject.toml), assets (images, demo gifs), and the main source code within the “src/proxy_lite” folder.
• Inside “src/proxy_lite” you find subdirectories:
• agents: Contains base agent code with “agent_base.py” and a specific “proxy_lite_agent.py”.
• browser: Manages web interaction (and includes JavaScript files for custom browser interaction and DOM element extraction).
• environments: Provides base classes and a web browser–specific environment (using Playwright, with stealth functionalities).
• solvers: Implements task-solving logic with a “simple_solver” as well as base interfaces.
• tools: Contains definitions for available tools (like BrowserTool and ReturnValueTool).
• Additional modules include configurations, logging, history handling, serialization, and command-line interface (cli.py).
• The project uses a Runner (in “runner.py”) that sets up and continuously cycles through tasks in a manner reminiscent of reinforcement learning (as described in the README).
Components and Their Relationships
• CLI and Web UI: The entry points into the system (e.g., “proxy” CLI command, “make app” for the web UI). This is where user tasks are initiated.
• Runner: The central orchestrator that initializes the configuration (using RunnerConfig) and starts a loop that ties together the solver and environment.
• Solver: Implements the decision-making logic. It selects the appropriate agent based on the task and interacts with it.
• Agent: The brain that interprets the task by building up a message history (with roles such as system and user) and then triggers actions (tool calls).
• Environment: For example, the webbrowser environment (which uses Playwright) where real-world actions (like clicking, typing) take place. It provides feedback (observations) back to the agent.
• Tools: Modules such as BrowserTool and ReturnValueTool define the set of actions available. They encapsulate functionality to interact with the external environment.
• Client / API Server Connection: Proxy Lite can be used to interact with a remote model endpoint (via vLLM and HuggingFace spaces). This involves preparing messages and handling model responses.
• Logger, Serializer, Recorder, and other supportive modules: They handle logging, data serialization (ensuring compatibility with OpenAI’s protocol), and recording interactions, thereby providing traceability through the cycle.
Architectural Patterns and Technologies
• Modularity: Each functional area (agent, solver, environment, tools) is encapsulated in its own module or package, making the system easily extendable.
• Pluggability: Use of configuration files (like the default.yaml) allows swapping out or configuring components (e.g., using a different environment or model endpoint).
• Reinforcement Learning Style Loop: The Runner sets off a continuous cycle (observe, think, act) similar to RL environments.
• Integration of Web Tools: The browser environment integrates with Playwright and injects custom JavaScript to enhance interaction reliability.
• The system also interfaces directly with external tools and APIs (like the vLLM server and HuggingFace endpoints) while ensuring a clear message format for communication.