# qwenlm/qwen-agent architecture

> Architecture diagram of the GitHub repository qwenlm/qwen-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qwenlm/qwen-agent
- Repository: https://github.com/qwenlm/qwen-agent

## Overview

1. **Repository purpose**
   - This is the Qwen-Agent framework: a Python SDK for building LLM applications that combine chat, tool use, planning, memory, RAG, and multi-agent orchestration.
   - The repo is not a single app; it is a platform with a core runtime, optional UI/server layers, examples, benchmarks, and documentation.

2. **Core package: `qwen_agent/`**
   - This is the central architecture.
   - It contains the generic **agent abstraction** (`agent.py`) plus a family of concrete agents in `qwen_agent/agents/` such as Assistant, ReAct, function-calling agents, router/multi-agent variants, document-QA agents, writing agents, and simulator agents.
   - These agents are the main orchestration layer that turns a user request into LLM calls, tool invocations, memory updates, and final answers.

3. **LLM provider layer: `qwen_agent/llm/`**
   - The framework isolates model access behind provider adapters.
   - It supports DashScope/Qwen APIs, OpenAI-compatible APIs, Azure, local/model-runtime backends like Transformers and OpenVINO, and multimodal variants for audio/VL/omni.
   - This layer also owns function-calling support and prompt templates for tool-call parsing, which is important for diagramming the boundary between “agent logic” and “model transport/protocol.”

4. **Tooling layer: `qwen_agent/tools/`**
   - Tools are first-class modules with a shared base interface and schema-driven registration.
   - Built-in tools include web search, retrieval, document parsing, image generation/search/zoom, Python execution, code interpreter, MCP manager, storage, and external utilities like weather.
   - The major boundary here is that tools are called by agents, but execute outside the LLM, often with their own I/O, storage, or sandbox constraints.

5. **Retrieval and document pipeline**
   - RAG is implemented through dedicated retrieval and search subsystems: `retrieval.py`, `search_tools/`, document parsers, and doc vocabulary extraction.
   - The flow is typically: ingest files/web content → parse/chunk/index → search or vector/hybrid retrieval → supply context back to the agent/LLM.
   - This is a separate architecture slice from plain chat, and it appears in the doc-QA agents and the example applications.

6. **Memory and state**
   - Conversation or agent memory is isolated in `qwen_agent/memory/`.
   - Memory is part of the agent runtime, not the model layer: agents read/write state across turns to support long dialogues, virtual memory, and multi-step workflows.
   - The architecture diagram should show memory as a shared state service used by several agents rather than a standalone app.

7. **Multi-agent and workflow orchestration**
   - `multi_agent_hub.py`, router agents, group chat agents, and the writing/doc-QA specializations show that the framework supports composition of multiple roles.
   - Common patterns include: routing a request to a specialized agent, sequentially decomposing tasks, or aggregating multiple subagent outputs.
   - This is an orchestration boundary above LLM/tool primitives.

8. **Sandboxed code execution**
   - The code interpreter and Python executor are separate execution environments, with Docker-based isolation for the code interpreter.
   - This is a key security boundary: the agent can request code execution, but the actual runtime is external to the model and intentionally sandboxed.
   - The repo also includes Docker image resources and kernel initialization helpers for this subsystem.

9. **Serving and UI layers**
   - `qwen_server/` provides server-side components for assistant/database/workstation-style services, with a small frontend bundle under the same tree.
   - `qwen_agent/gui/` provides a Gradio-based web UI for quickly wrapping any agent.
   - These are presentation/hosting layers over the same core agent runtime; they do not replace the core orchestration model.

10. **Browser and extension integration**
   - `browser_qwen/` contains a browser extension-style assistant frontend, with content scripts, popup UI, and background script.
   - This indicates the framework can be embedded into browser workflows, likely calling back into the agent runtime or server layer for assistance actions.

11. **Benchmark suites**
   - `benchmark/code_interpreter/` and `benchmark/deepplanning/` are self-contained evaluation harnesses, not production features.
   - Code Interpreter benchmark focuses on model/tool execution and metrics; DeepPlanning includes shopping and travel planning tasks with domain tools, evaluation pipelines, and result aggregation.
   - For architecture diagrams, treat benchmarks as consumer workloads that exercise the same agent/tool/LLM stack under controlled datasets and metrics.

12. **Examples and cookbook applications**
   - `examples/` is a large catalog of end-to-end scenarios: RAG, audio, multimodal, function calling, long dialogue, math/tool-integrated reasoning, group chat, custom tools, and MCP.
   - These examples are valuable because they reveal the intended integration patterns: agent + model config + tools + optional files/UI.
   - They are not core subsystems, but they demonstrate how the framework is assembled in real deployments.

13. **Documentation and release automation**
   - `qwen-agent-docs/website` is a separate Next.js documentation site with localized content and benchmark pages.
   - `.github/workflows/deploy-docs.yml` shows docs publishing automation.
   - This is infrastructure around the framework, not part of the runtime path.

14. **Primary runtime data flow**
   - Typical flow: user message or external event → agent orchestration → LLM call → tool selection or function call → tool execution / retrieval / memory updates → optional follow-up LLM calls → response.
   - For multimodal or document-driven cases, files/images/web content enter through tools or agent inputs first, then get parsed or indexed before being reasoned over.
   - The key diagram boundaries are: frontend/UI, agent orchestration, LLM provider, tools/execution sandbox, retrieval/memory, and external services.

Main entry points: [`qwen_agent/agents`](https://github.com/qwenlm/qwen-agent/tree/main/qwen_agent/agents) (Agent family), [`examples`](https://github.com/qwenlm/qwen-agent/tree/main/examples) (Examples), [`qwen_agent/agent.py`](https://github.com/qwenlm/qwen-agent/blob/main/qwen_agent/agent.py) (Agent base), [`qwen_agent/llm`](https://github.com/qwenlm/qwen-agent/tree/main/qwen_agent/llm) (LLM adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_agent_core["Agent base<br/>runtime core<br/>[agent.py]"]
  node_agent_family["Agent family<br/>orchestration"]
  node_multi_agent_hub["Multi-agent hub<br/>orchestration hub<br/>[multi_agent_hub.py]"]
  node_llm_layer["LLM adapters<br/>provider layer"]
  node_fncall_prompts["Fn-call prompts<br/>protocol support"]
  node_tool_base["Tool base<br/>tooling contract<br/>[base.py]"]
  node_tool_suite["Tool suite<br/>tools"]
  node_retrieval_pipeline["Retrieval pipeline<br/>rag pipeline<br/>[retrieval.py]"]
  node_search_backends["Search backends<br/>search subsystem"]
  node_memory_layer[("Memory layer<br/>state service<br/>[memory.py]")]
  node_code_exec["Code execution<br/>sandboxed exec"]
end

subgraph group_interfaces["Interfaces"]
  node_gui["Gradio UI<br/>ui layer<br/>[web_ui.py]"]
  node_server["Qwen server<br/>serving layer"]
  node_browser_ext["Browser assistant<br/>browser extension"]
end

subgraph group_workloads["Workloads"]
  node_examples["Examples<br/>usage gallery"]
  node_code_benchmark["Code benchmark<br/>eval harness"]
  node_planning_benchmark["Planning benchmark<br/>eval harness"]
end

subgraph group_docs["Docs"]
  node_docs_site["Docs site<br/>documentation app"]
end

node_agent_core -->|"implements"| node_agent_family
node_agent_family -->|"calls"| node_llm_layer
node_agent_family -->|"uses"| node_tool_base
node_tool_suite -->|"implements"| node_tool_base
node_agent_family -->|"uses"| node_retrieval_pipeline
node_retrieval_pipeline -->|"depends on"| node_search_backends
node_agent_family -->|"reads/writes"| node_memory_layer
node_agent_family -->|"can invoke"| node_code_exec
node_multi_agent_hub -->|"coordinates"| node_agent_family
node_gui -->|"hosts"| node_agent_core
node_server -->|"serves"| node_agent_core
node_browser_ext -->|"connects to"| node_server
node_examples -->|"demonstrates"| node_agent_family
node_examples -->|"configures"| node_llm_layer
node_examples -->|"uses"| node_tool_suite
node_code_benchmark -->|"evaluates"| node_llm_layer
node_code_benchmark -->|"tests"| node_code_exec
node_planning_benchmark -->|"evaluates"| node_agent_family
node_docs_site -->|"documents"| node_examples
node_docs_site -->|"documents"| node_agent_family

click node_agent_core "https://github.com/qwenlm/qwen-agent/blob/main/qwen_agent/agent.py"
click node_agent_family "https://github.com/qwenlm/qwen-agent/tree/main/qwen_agent/agents"
click node_multi_agent_hub "https://github.com/qwenlm/qwen-agent/blob/main/qwen_agent/multi_agent_hub.py"
click node_llm_layer "https://github.com/qwenlm/qwen-agent/tree/main/qwen_agent/llm"
click node_fncall_prompts "https://github.com/qwenlm/qwen-agent/tree/main/qwen_agent/llm/fncall_prompts"
click node_tool_base "https://github.com/qwenlm/qwen-agent/blob/main/qwen_agent/tools/base.py"
click node_tool_suite "https://github.com/qwenlm/qwen-agent/tree/main/qwen_agent/tools"
click node_retrieval_pipeline "https://github.com/qwenlm/qwen-agent/blob/main/qwen_agent/tools/retrieval.py"
click node_search_backends "https://github.com/qwenlm/qwen-agent/tree/main/qwen_agent/tools/search_tools"
click node_memory_layer "https://github.com/qwenlm/qwen-agent/blob/main/qwen_agent/memory/memory.py"
click node_code_exec "https://github.com/qwenlm/qwen-agent/blob/main/qwen_agent/tools/code_interpreter.py"
click node_gui "https://github.com/qwenlm/qwen-agent/blob/main/qwen_agent/gui/web_ui.py"
click node_server "https://github.com/qwenlm/qwen-agent/tree/main/qwen_server"
click node_browser_ext "https://github.com/qwenlm/qwen-agent/tree/main/browser_qwen"
click node_examples "https://github.com/qwenlm/qwen-agent/tree/main/examples"
click node_code_benchmark "https://github.com/qwenlm/qwen-agent/tree/main/benchmark/code_interpreter"
click node_planning_benchmark "https://github.com/qwenlm/qwen-agent/tree/main/benchmark/deepplanning"
click node_docs_site "https://github.com/qwenlm/qwen-agent/tree/main/qwen-agent-docs/website"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent_core,node_agent_family,node_multi_agent_hub,node_llm_layer,node_fncall_prompts,node_tool_base,node_tool_suite,node_retrieval_pipeline,node_search_backends,node_memory_layer,node_code_exec toneBlue
class node_gui,node_server,node_browser_ext toneAmber
class node_examples,node_code_benchmark,node_planning_benchmark toneMint
class node_docs_site toneRose
```

## Components

### Core runtime

Agent orchestration, model adapters, tools, retrieval, and memory.

- [Agent base](https://github.com/qwenlm/qwen-agent/blob/main/qwen_agent/agent.py): runtime core · Shared agent abstraction and turn-by-turn orchestration contract. · `qwen_agent/agent.py`
- [Agent family](https://github.com/qwenlm/qwen-agent/tree/main/qwen_agent/agents): orchestration · Specialized agents for chat, ReAct, routing, document QA, writing, memory, and simulation. · `qwen_agent/agents`
- [Multi-agent hub](https://github.com/qwenlm/qwen-agent/blob/main/qwen_agent/multi_agent_hub.py): orchestration hub · Coordination layer for agent composition and shared dispatch patterns. · `qwen_agent/multi_agent_hub.py`
- [LLM adapters](https://github.com/qwenlm/qwen-agent/tree/main/qwen_agent/llm): provider layer · Model backends and protocol adapters for DashScope, OpenAI-compatible, Azure, local runtimes, and multimodal variants. · `qwen_agent/llm`
- [Fn-call prompts](https://github.com/qwenlm/qwen-agent/tree/main/qwen_agent/llm/fncall_prompts): protocol support · Prompt templates and helpers for function-call parsing and tool-call framing. · `qwen_agent/llm/fncall_prompts`
- [Tool base](https://github.com/qwenlm/qwen-agent/blob/main/qwen_agent/tools/base.py): tooling contract · Shared tool interface and schema registration for external capabilities. · `qwen_agent/tools/base.py`
- [Tool suite](https://github.com/qwenlm/qwen-agent/tree/main/qwen_agent/tools): tools · Built-in tools for web search, retrieval, parsing, image ops, Python execution, code interpreter, MCP, storage, and utilities. · `qwen_agent/tools`
- [Retrieval pipeline](https://github.com/qwenlm/qwen-agent/blob/main/qwen_agent/tools/retrieval.py): rag pipeline · Document ingestion, parsing, indexing, and search helpers used by RAG and doc-QA flows. · `qwen_agent/tools/retrieval.py`
- [Search backends](https://github.com/qwenlm/qwen-agent/tree/main/qwen_agent/tools/search_tools): search subsystem · Keyword, vector, hybrid, and front-page search implementations. · `qwen_agent/tools/search_tools`
- [Memory layer](https://github.com/qwenlm/qwen-agent/blob/main/qwen_agent/memory/memory.py): state service · Conversation and agent state across turns and workflows. · `qwen_agent/memory/memory.py`
- [Code execution](https://github.com/qwenlm/qwen-agent/blob/main/qwen_agent/tools/code_interpreter.py): sandboxed exec · Python executor and code interpreter sandbox boundary, including Docker-based resources. · `qwen_agent/tools/code_interpreter.py`

### Interfaces

Serving, UI, and browser entrypoints on top of the core runtime.

- [Gradio UI](https://github.com/qwenlm/qwen-agent/blob/main/qwen_agent/gui/web_ui.py): ui layer · Lightweight web UI wrapper for interacting with agents. · `qwen_agent/gui/web_ui.py`
- [Qwen server](https://github.com/qwenlm/qwen-agent/tree/main/qwen_server): serving layer · Assistant, database, and workstation server components with frontend assets. · `qwen_server`
- [Browser assistant](https://github.com/qwenlm/qwen-agent/tree/main/browser_qwen): browser extension · Content script, popup, and background extension frontend. · `browser_qwen`

### Workloads

Examples and benchmarks that exercise the framework.

- [Examples](https://github.com/qwenlm/qwen-agent/tree/main/examples): usage gallery · End-to-end sample applications for chat, RAG, multimodal, tool use, routing, and multi-agent patterns. · `examples`
- [Code benchmark](https://github.com/qwenlm/qwen-agent/tree/main/benchmark/code_interpreter): eval harness · Benchmark for code-interpreter style reasoning, execution, and metrics. · `benchmark/code_interpreter`
- [Planning benchmark](https://github.com/qwenlm/qwen-agent/tree/main/benchmark/deepplanning): eval harness · DeepPlanning shopping and travel evaluation pipelines with domain tools and scoring. · `benchmark/deepplanning`

### Docs

Documentation site and publishing automation.

- [Docs site](https://github.com/qwenlm/qwen-agent/tree/main/qwen-agent-docs/website): documentation app · Next.js documentation site with guides, benchmarks, and localized content. · `qwen-agent-docs/website`

## Connections

- Agent base → Agent family: implements · Concrete agents build on the shared agent abstraction.
- Agent family → LLM adapters: calls · Agents delegate reasoning and generation to model adapters.
- Agent family → Tool base: uses · Agents invoke tools through the common tool interface.
- Tool suite → Tool base: implements · Built-in tools conform to the shared contract.
- Agent family → Retrieval pipeline: uses · Doc-QA and RAG agents pull context through retrieval flows.
- Retrieval pipeline → Search backends: depends on · Retrieval combines search implementations and indexing strategies.
- Agent family → Memory layer: reads/writes · Agents persist dialogue and workflow state across turns.
- Agent family → Code execution: can invoke · Some agents request sandboxed code execution or notebook-like actions.
- Multi-agent hub → Agent family: coordinates · Multi-agent flows route, compose, and aggregate agent behavior.
- Gradio UI → Agent base: hosts · The UI wraps the core agent runtime for interactive use.
- Qwen server → Agent base: serves · Server endpoints expose the same agent runtime to external clients.
- Browser assistant → Qwen server: connects to · The extension frontend typically bridges to hosted assistance services.
- Examples → Agent family: demonstrates · Examples show how to assemble agents with models, tools, and memory.
- Examples → LLM adapters: configures · Example apps select model backends and prompt styles.
- Examples → Tool suite: uses · Examples exercise built-in and custom tools.
- Code benchmark → LLM adapters: evaluates · The benchmark measures model/tool interaction under controlled tasks.
- Code benchmark → Code execution: tests · Code-interpreter evaluation focuses on execution behavior and metrics.
- Planning benchmark → Agent family: evaluates · Planning tasks exercise agentic decomposition and tool use.
- Docs site → Examples: documents · Docs describe usage patterns and benchmark results.
- Docs site → Agent family: documents · Guides explain the core agent, LLM, tool, context, and RAG modules.
