Qwen-Agent APIs: Complete Guide to the FastAPI Endpoint and Internal Methods

Qwen-Agent exposes a single HTTP POST endpoint at /endpoint that handles three specific tasks—change_checkbox, cache, and pop_url—while additional capabilities are accessed through the Python SDK or Gradio UI.

The Qwen-Agent framework from the QwenLM/Qwen-Agent repository provides a lightweight server architecture for managing browsing history, caching web content, and handling popup URLs. Understanding the available Qwen-Agent APIs requires examining both the public REST interface and the internal Python methods that power the agent's functionality.

Overview of Qwen-Agent API Architecture

The Single HTTP Endpoint

Unlike comprehensive AI platforms that expose dozens of REST endpoints, Qwen-Agent adopts a minimalist approach with a single generic entry point. The API is implemented using FastAPI and defined in qwen_server/database_server.py. This design consolidates all server-side operations through the /endpoint route, which dispatches requests based on a task field in the JSON payload.

The server runs as a subprocess launched by run_server.py, reading configuration from qwen_server/server_config.json (modeled by Pydantic schemas in qwen_server/schema.py). The specific port is controlled by the fast_api_port setting in this configuration file.

Configuration and Server Startup

When the server initializes, it loads the global configuration to determine network parameters and workspace directories. The run_server.py script orchestrates three separate processes: the database server (FastAPI), the workstation server, and the assistant server. Only the database server exposes the HTTP API endpoint.

Available Qwen-Agent API Endpoints and Methods

POST /endpoint: The Generic Task Handler

The /endpoint route accepts POST requests containing a JSON object with a mandatory task key. Based on the task value, the server executes one of three distinct operations:

change_checkbox – Toggles the checked state of a browsing record. This task invokes change_checkbox_state() (defined at lines 82-88 in qwen_server/database_server.py), which updates the meta_data.jsonl file to mark records as selected or deselected.

cache – Asynchronously caches web page content or local files into the workspace. This task spawns a separate process running cache_page() (lines 91-112), which stores the content and extracts a title using the Memory module. The function returns immediately with the status 'caching' while the background process completes the storage operation.

pop_url – Adds a new URL or local file path to the popup list for UI display. This task calls update_pop_url() (lines 71-79), which appends the URL to popup_url.jsonl for retrieval by the frontend interface.

The handler implementation explicitly raises NotImplementedError for any unrecognized task values, ensuring strict validation of inputs.

How to Call Qwen-Agent APIs: Code Examples

Using cURL to Interact with the API

You can test the Qwen-Agent API directly from the command line using standard HTTP tools. Ensure the server is running (default port typically 8000 unless configured otherwise in server_config.json):

# Toggle the checkbox state for a specific record

curl -X POST http://127.0.0.1:8000/endpoint \
     -H "Content-Type: application/json" \
     -d '{"task":"change_checkbox","ckid":"ck-<record_id>"}'

# Asynchronously cache a web page

curl -X POST http://127.0.0.1:8000/endpoint \
     -H "Content-Type: application/json" \
     -d '{"task":"cache","url":"https://example.com","content":"<html>...</html>"}'

# Add a URL to the popup list

curl -X POST http://127.0.0.1:8000/endpoint \
     -H "Content-Type: application/json" \
     -d '{"task":"pop_url","url":"https://example.com/article.pdf"}'

Python requests Implementation

For programmatic access, use the requests library to construct type-safe clients:

import requests

BASE_URL = "http://127.0.0.1:8000/endpoint"

def call_qwen_agent_api(task, **kwargs):
    """Generic caller for the Qwen-Agent API."""
    payload = {"task": task, **kwargs}
    response = requests.post(BASE_URL, json=payload)
    response.raise_for_status()
    return response.json()

# Toggle checkbox state

result = call_qwen_agent_api("change_checkbox", ckid="ck-12345")
print(result)  # Output: {'result': 'changed'}

# Cache content asynchronously

result = call_qwen_agent_api(
    "cache", 
    url="https://example.com", 
    content="<p>Hello World</p>"
)
print(result)  # Output: 'caching'

# Update popup URL list

result = call_qwen_agent_api("pop_url", url="https://example.com/report.pdf")
print(result)  # Output: 'Update URL'

Direct Python Function Calls (Internal API)

Developers integrating Qwen-Agent components directly can bypass the HTTP layer and invoke the underlying functions from qwen_server.database_server:

from qwen_server.database_server import (
    change_checkbox_state, 
    cache_page, 
    update_pop_url
)

# Synchronously toggle checkbox (updates meta_data.jsonl)

change_checkbox_state("ck-12345")

# Synchronously cache page content (uses Memory module for title extraction)

cache_page(
    url="https://example.com", 
    content="<html><head><title>Example</title></head><body>...</body></html>"
)

# Update popup URL list (writes to popup_url.jsonl)

update_pop_url("https://example.com/report.pdf")

Note that cache_page runs synchronously when called directly, whereas the HTTP API spawns it as a background process via multiprocessing.Process.

Key Files and Implementation Details

The Qwen-Agent API implementation spans several critical files in the repository:

File	Role
qwen_server/database_server.py	Implements the FastAPI application and the /endpoint route handler (web_listening), plus utility functions change_checkbox_state(), cache_page(), and update_pop_url().
qwen_server/schema.py	Defines Pydantic models (GlobalConfig, ServerConfig, PathConfig) that validate server_config.json structure.
qwen_server/utils.py	Provides helper functions for persisting browsing metadata and chat history to JSONL files.
run_server.py	Orchestrates the three-server architecture (database, workstation, assistant) and launches the FastAPI subprocess.
qwen_server/server_config.json	Configuration file specifying fast_api_port and workspace directories.

These files collectively define the public API surface of Qwen-Agent. The REST endpoint (POST /endpoint) represents the only network-exposed API; all other agent capabilities—including chat completions, writing assistance, and code interpretation—are accessed through the Python SDK (qwen_agent package) or the Gradio web interface.

Summary

• Qwen-Agent exposes a single HTTP API via FastAPI at POST /endpoint, defined in qwen_server/database_server.py.
• Three task types are supported: change_checkbox (toggle record selection), cache (asynchronously store web content), and pop_url (add URLs to the popup list).
• Configuration is managed through qwen_server/server_config.json and validated by Pydantic schemas in qwen_server/schema.py.
• Server startup is handled by run_server.py, which launches the database server as a subprocess on the port specified by fast_api_port.
• Alternative access to the same functionality is available through direct Python imports from qwen_server.database_server for developers integrating the framework internally.

Frequently Asked Questions

Does Qwen-Agent provide a REST API for chat completions?

No, the Qwen-Agent framework does not expose chat completion functionality through a REST API. The only network-exposed endpoint is POST /endpoint in qwen_server/database_server.py, which handles browsing record management and content caching. Chat, writing, and code interpreter capabilities are accessed through the Gradio web UI or the qwen_agent Python SDK.

What is the default port for the Qwen-Agent API server?

The Qwen-Agent API server port is not hardcoded; it is read from the fast_api_port field in qwen_server/server_config.json. This configuration is validated by the ServerConfig Pydantic model in qwen_server/schema.py when run_server.py launches the database server subprocess.

Can I use Qwen-Agent functionality without the HTTP API?

Yes, developers can bypass the HTTP layer entirely by importing functions directly from qwen_server.database_server. The internal Python API exposes change_checkbox_state(), cache_page(), and update_pop_url(), which perform the same operations as the REST endpoint but run synchronously in the current process rather than through the FastAPI server.

Where is the API endpoint handler implemented in the source code?

The /endpoint route handler is implemented as the web_listening async function in qwen_server/database_server.py (lines 115-132). This function parses the incoming JSON payload, dispatches to the appropriate utility function based on the task field, and returns a JSONResponse. The FastAPI application setup and route registration occur in the same file, which is launched as a subprocess by run_server.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}