uag — Universal AI Gateway

Universal AI Gateway — Your environment, your freedom.

File ops / Web search / Image generation & analysis / PDF & Excel extraction / IoT control / MCP integration
15+ providers / 3 UIs / Parallel tool execution / Agent Skills marketplace

GitHub · PyPI · Read this in your language

Why uag?

Break free from vendor lock-in. Most AI assistants tie you to a specific provider or cloud service. uag is different.

• Runs locally on your machine. Your data stays with you (except API calls you make).
• Provider freedom: OpenAI, Claude, Gemini, DeepSeek, Ollama, Azure, Bedrock, HuggingFace... 15+ providers, all accessible from a single interface. Swap between them by reconfiguring environment variables — no reinstall, no migration.
• 131 tools: File I/O, web search, image generation, Gmail, BLE device scanning, MCP server integration — 76 are parallel-safe (up to 8 execute concurrently via thread pool, configurable via UAGENT_PARALLEL_WORKERS). When the LLM fires multiple tool calls at once, uag automatically parallelizes them.
• 3 UIs + A2A: CLI, GUI, Web, and Agent-to-Agent protocol. Same engine, any interface.
• IoT ready: SwitchBot, ECHONET Lite, Matter, UPnP — control your home devices through AI.
• Agent Skills: Install community-built skills from the marketplace. Extend uag endlessly.

uag is your AI assistant on your terms. Not tied to a provider, not tied to an interface, not tied to a platform.

Quick Start

pip install uag
uag

On first launch, the setup wizard walks you through provider configuration. See ENVIRONMENT.md for all environment variables.

Features

🧠 Multi-Provider Architecture

OpenAI / Azure / Bedrock / OpenRouter / Ollama / Gemini / Vertex AI / Claude / Grok / NVIDIA / DeepSeek / Z.AI (Zhipu AI) / HuggingFace / Alibaba Cloud (Qwen) / KIMI (Moonshot AI) / Xiaomi MiMo / LM Studio / MiniMax / Sakana AI (Fugu)

All providers share the same toolset and interface. Switch by setting UAGENT_PROVIDER — no code changes, no separate installations.

⚡ Parallel Tool Execution

When the LLM requests multiple tools simultaneously, uag automatically parallelizes them. 76 tools are marked x_parallel_safe and execute concurrently via a ThreadPoolExecutor (8 threads by default; set UAGENT_PARALLEL_WORKERS to change).

Example: Ask "Check the weather in Nordic capitals" → LLM fires search_web × 5 countries → all 5 searches run in parallel → results collected in one batch.

Read-only tools (file search, hash calculation, directory listing, translation, DB queries, etc.) are aggressively parallelized.

🔄 Session Continuity

• Switch providers mid-session with UAGENT_PROVIDER — conversation history is preserved.
• Reload past sessions with :load <index> — pick up where you left off.
• Tool result caching avoids redundant re-execution when the same tool call repeats.

🛠 131 Tools

🖥 4 Interfaces + VS Code Extension

See VSCODE.md for details on the VS Code extension — installation, commands, keybindings, and configuration.

🏠 IoT Device Control

• SwitchBot: Cloud batch control & BLE scan/control
• ECHONET Lite: Discover and control home appliances (AC, lights, water heaters, etc.) on local network
• Matter: Read-only inspection of controller/bridge/device topology
• UPnP: Device discovery & IGD port forwarding

See IOT_USECASE.md

🎯 Agent Skills Marketplace

:skills mp_search to browse SkillsMP and ClawHub for community skills. Install and extend uag's capabilities on the fly.

🤖 Auto-Pilot (:auto)

uag can autonomously pursue a goal across multiple LLM rounds. Perfect for complex, multi-step tasks that need iterative refinement.

• How it works: Each round has a main query (Step A) followed by a reviewer judgment (Step B) that decides "COMPLETE or CONTINUE?"
• Same provider, same API: The reviewer judgment uses the identical code path as the main query — including Responses API support.
• Separate judge LLM (optional): Set UAGENT_AP_PROVIDER to use a different provider/model for the reviewer (e.g. use a cheaper model for judging).
• Exit anytime: Press x key to stop immediately, even mid-response. Or let the reviewer decide when the goal is met.
• Configurable: --max-rounds N to control the budget.

See README_AUTO.md for full documentation.

🧩 Batch State Manager

uag can track progress across long-running multi-file tasks. When the LLM processes dozens of files, batch_state persists the list of pending, completed, and failed files to disk. If the session ends or a round times out, the next run resumes from where it stopped — nothing gets lost.

🛡 Human-in-the-Loop

human_ask lets the LLM pause and ask for your confirmation before performing destructive operations (file deletion, overwrites, shell commands). You stay in control.

🛑 Interrupt (c-key / Stop button)

Stop LLM response generation at any time and inject a stop command back to the LLM.

The interrupt works as "prompt injection": instead of just aborting, it feeds "Stop" back to the LLM as a user message, allowing it to gracefully conclude or acknowledge the interruption.

Press x key to exit auto-pilot mode (see README_AUTO.md).

🕵️ Browser Automation & Web Inspector

Two complementary Playwright-based tools:

• browser_playwright: Automate real browser sessions — navigate, click, fill forms, extract data, handle multi-page flows. Works headless or headed.
• playwright_inspector: Record browser transitions, capture DOM snapshots and screenshots at each step. Useful for debugging web interactions or auditing page changes over time.

🔄 Dynamic Tool Loading

tool_catalog and tool_load let you discover and enable tools at runtime. No need to load everything at startup — activate only what you need, when you need it.

🌐 i18n / L10n

日本語 / English / 简体中文 / 繁體中文 / 한국어 / Español / Français / Русский / and more. Set UAGENT_LANG to switch. See ADD_LOCALE.md to add a new locale.

Translations of this README are available in docs/README.translations.md.

🔒 Encrypted Environment Variables

Store API keys and secrets in .env.sec — an encrypted .env file. Manage with uag_envsec.

Configuration & Details

• Environment variables: ENVIRONMENT.md
• Setup wizard: python -m uagent.setup_cli
• Encrypted env: uag_envsec — encrypt .env as .env.sec
• Responses API: Set UAGENT_RESPONSES=1 for Responses API mode (OpenAI/Azure/Bedrock/OpenRouter/Ollama/Alibaba/LM Studio/Sakana AI). Auto-enabled for Sakana AI (Fugu).
• Developer docs: DEVELOP.md
• Small LLM tips: SLM_TIPS.md

Project Philosophy

uag aspires to be your AI, on your machine, on your terms.

• No SaaS dependency — runs locally
• No provider lock-in — switch anytime
• No UI lock-in — CLI / GUI / Web / A2A
• No feature lock-in — extend with tools and skills

A free AI agent experience, free from vendor lock-in.