DOCSEARCHbyAlgolia
Submit Docs

MagenticLite

repository·main·Indexed 27 days ago

https://github.com/microsoft/magentic-ui

A research prototype of a human-centered interface powered by a multi-agent system. MagenticLite uses an orchestrator model (MagenticBrain) and a specialized browser-use model (Fara) to automate tasks across web browsers and local file systems within a VM sandbox. It supports OpenAI-compatible servers and Azure OpenAI, offering various agent modes (all, omniagent_only, websurfer_only) and configurable tool approval policies for safety.

Tokens
17.3K
Snippets
49
Records
111
Agent score
95%

What's inside magentic-ui

  1. Overview of MagenticLite (Magentic 2.0)

    main

    MagenticLite (also known as Magentic 2.0) is an open-source agentic application designed to work across web browsers and local file systems. It is optimized for Small Language Models (SLMs), making it faster and more cost-effective than previous versions.

    Key capabilities include:

    • Web research and form filling.
    • Local file management and data analysis.
    • Code writing and execution.
    • Full visibility of reasoning traces and actions, allowing users to steer the agent via natural language or direct browser control.

    Note: If you require the previous version optimized for frontier models, use the magentic-ui-0.1.x branch.

  2. Security warning: Running MagenticLite as a shared service

    main

    MagenticLite is designed for local use only. It is not recommended to host it as a shared service because:

    • UX Degradation: It was not designed for concurrent multi-user sessions.
    • Security Risk: The app exposes host-level capabilities, including file-system mounting controls. Hosting it as a service effectively grants any user who can reach the URL the same file-system access as the host account. Treat the service URL as equivalent to shell access to the host machine.

  3. Understand MagenticLite limitations

    main

    MagenticLite is a research prototype and has several known functional limitations. Be aware of these constraints when designing tasks:

    • Summarization: Long source texts may result in oversimplified or unfaithful summaries.
    • Conversation Length: Quality of performance degrades as multi-turn conversation history grows.
    • Steering Persistence: If you redirect the browser-use agent (Fara) mid-task, MagenticBrain may ignore corrections and return to the original sub-task plan.
    • Context Size: Very large files or contexts that exceed typical chat-sized prompts will fail or be truncated.
    • File Uploads: The agent cannot complete web flows that require attaching files from your local disk via a webpage's upload control.
    • Image Inputs: Tasks requiring the agent to process image files (e.g., "describe this picture") are not supported.

  4. Connect MagenticLite to Microsoft Foundry Managed Compute

    main

    After deploying your models in Foundry, you must provide the connection details to MagenticLite via the Browser use model and Orchestrator cards (found in Settings → Models if onboarding is complete).

    Required Credentials

    Retrieve these from your Foundry project under Models + endpoints:

    • Endpoint URL: From the Details tab, copy the REST endpoint through /v1 (e.g., https://<endpoint-name>.<region>.inference.ml.azure.com/v1).
    • Model Name: Use the segment after /models/ from the deployment details (e.g., Fara1.5-9B or MagenticBrain-14B). Do not use the deployment name.
    • API Key: From the Consume tab, copy the Primary key.

    Configuration Mapping

    FieldBrowser use model (Fara)Orchestrator model (MagenticBrain)
    Endpoint URLhttps://<fara-endpoint>.<region>.inference.ml.azure.com/v1https://<brain-endpoint>.<region>.inference.ml.azure.com/v1
    Model NameFara1.5-9BMagenticBrain-14B
    API KeyPrimary key from Fara endpointPrimary key from MagenticBrain endpoint

    Click Verify & Save to confirm the connection.

  5. Install and run MagenticLite

    main

    Once prerequisites are installed, follow these steps to set up a project directory, create a virtual environment, and run MagenticLite.

    Note: Only one MagenticLite instance can run at a time on the same port (default 8081).

    # Create a project directory
makergnetic-lite && cd magentic-lite

# Create and activate a virtual environment
uv venv --python=3.12 --seed .venv
source .venv/bin/activate

# Install the latest 0.2.x release from PyPI
uv pip install "magentic_ui>=0.2.0"

# Run
magentic-ui --port 8081

  6. Configure MagenticLite via YAML

    main

    While most users can use the in-app Settings panel, you can also use a config.yaml file to manage settings. This is useful for sharing setups or checking them into source control.

    To use a YAML configuration, copy the provided example and pass it to the CLI using the --config flag:

    1. Copy the example: cp config.yaml.example config.yaml
    2. Edit config.yaml with your desired settings.
    3. Launch the app: magentic-ui --port 8081 --config config.yaml

    Note on Persistence: MagenticLite stores effective configuration in a local database. When using --config, the values in your YAML file are merged into the database at startup. Fields explicitly set in the YAML will overwrite existing database values for that session, effectively pinning them to the file's values on every launch.

    cp config.yaml.example config.yaml
# then edit config.yaml to taste, and pass it on launch:
magentic-ui --port 8081 --config config.yaml

  7. MagenticLite Intended and Out-of-Scope Uses

    main

    Intended Uses

    MagenticLite is a research prototype intended for domain experts to explore agentic assistance for tasks requiring web navigation and local file interaction. Examples include:

    • Filling online forms and making bookings.
    • Researching and analyzing information across the web and local files.
    • Managing local file systems.
    • Completing simple local coding tasks.

    Out-of-Scope Uses

    Do not use MagenticLite for:

    • Tasks relying on audio or video data.
    • Long-duration tasks (e.g., summarizing 100+ papers).
    • Real-time fast actions (e.g., playing online games).
    • High-stakes or regulated domains: Avoid use in law enforcement, legal, finance, or healthcare where inaccurate outputs could lead to injury or negatively impact life opportunities.
    • Commercial applications: It is currently released for research purposes and should not be used in commercial settings without further testing and development.

  8. Run MagenticLite in Frontend Dev mode

    main

    Use this mode when iterating on the UI. It runs the Vite dev server with hot reload in one terminal and the backend in another. The Vite dev server (running on port 5173) automatically proxies API and WebSocket calls to the backend on port 8081.

    ```bash
# Terminal 1 — backend
source .venv/bin/activate
magentic-ui --port 8081

# Terminal 2 — frontend dev server
cd frontend
pnpm dev

    Access the application at http://localhost:5173/.

  9. Set up the MagenticLite backend from source

    main

    After cloning the repository, set up the backend using uv. This installs MagenticLite in editable mode along with all development dependencies. Note that the Quicksand VM image is downloaded automatically during the first launch of magentic-ui.

    git clone https://github.com/microsoft/magentic-ui.git
cd magentic-ui

uv venv --python=3.12 --seed .venv
source .venv/bin/activate
uv sync --all-extras

  10. Install Node.js and pnpm for frontend development

    main

    Building the MagenticLite frontend requires Node.js v24 or later and pnpm v10+. You can install these using nvm and npm as shown below:

    # Install Node via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 24

# Install pnpm
npm install -g pnpm

  11. Deploy models using Microsoft Foundry Managed Compute

    main

    To use MagenticLite with Microsoft Foundry Managed Compute, you must deploy model roles (Browser use and/or Orchestrator) as managed endpoints.

    Prerequisites

    • An Azure subscription with a valid payment method (Free/trial subscriptions do not support GPU deployments).
    • A hub-based project in Foundry (Newer "Foundry project" types are not supported). Create one via + New project → Hub-based project in the Foundry portal.
    • Quota: Request Standard NCADSA100v4 Family Cluster Dedicated vCPUs in the same region as your project via Azure Quotas. For a standard setup with both Fara and MagenticBrain running at 1 instance each, request 48 dedicated vCPUs.

    Deployment Steps

    1. Open the model card in Foundry Explore models: Fara1.5-9B (for browser use) or MagenticBrain-14B (for orchestration).
    2. Click Use this model and select your hub-based project. Pick a region with GPU inventory (e.g., East US 2 or Sweden Central).
    3. Select Managed Compute in the deployment wizard.
    4. Configure the deployment:
      • Endpoint name: e.g., fara-15-9b-magentic-lite (becomes part of the URL).
      • Deployment name: e.g., fara1-5-9b-1 (for tracking).
      • Virtual machine: Standard_NC24ads_A100_v4 is recommended for testing.
      • Instance count: Set to 1 for testing/single-user use to manage costs.
    5. Click Deploy. Provisioning takes ~15–20 minutes. Note: Billing starts as soon as the VM is allocated.

  12. Follow best practices for limiting data exposure in MagenticLite

    main

    To minimize the risk of data leakage and unintended actions, follow these recommended practices:

    • Grant the agent access only to the folders strictly necessary for the task.
    • Avoid logging into websites through the agent unless absolutely required.
    • Never share sensitive data that you would not be comfortable sending to external model providers (as browser screenshots are shared with model providers).
    • Use the recommended model configuration (Fara1.5 + MagenticBrain) to ensure critical point detection is active.