XAgent: A Planner and Actor Agent That Runs Its Tools Inside Docker

The problem XAgent targets: long tasks that outlive one prompt

A single prompt and a single model reply handle short requests well. They handle a request like research a topic, write code, test it, and produce a file far less well, because the work needs state that survives across many model calls. XAgent is built for that second category. The README describes it as an open-source experimental LLM-driven autonomous agent that can automatically solve various tasks, and the feature list leads with autonomy: solving tasks without human participation. The intended user is someone who wants to hand over a multi-step job and inspect the transcript afterwards, not someone who wants a chat interface.

The README is explicit that this is early work. It says XAgent is still in its early stages and that the team is working to improve it. That framing matters when you weigh the rest of the material. This is not a product with a support contract. It is a reference implementation of an agent architecture, published under Apache-2.0, with a documented workflow and a container-based tool layer. The second feature in the list, safety, is the one that shapes the whole design: all actions are constrained inside a docker container. If you are evaluating XAgent, that constraint is the thing to evaluate first, because it determines both what the agent can do and what you have to operate.

Dispatcher, Planner, Actor: the three moving parts and what each one owns

The README names three components. The Dispatcher dynamically instantiates and dispatches tasks to different agents, and the README frames it as the extension point for adding new agents. The Planner generates and rectifies plans, dividing a task into subtasks and generating milestones so the agent can proceed step by step. The Actor performs actions to achieve goals and finish subtasks, using tools, and it can also collaborate with humans.

The interesting word in that description is rectifies. A planner that only decomposes a task once is a prompt template. A planner that revises milestones implies a loop: plan, act, observe, adjust. The README does not spell out the loop's termination conditions or how many revision cycles are permitted, so treat the control flow as documented at the level of responsibilities rather than as a specification. What is documented is the separation of concerns. Planning and acting are different jobs handled by different components, and dispatch sits above both. That structure is why the extension story is about adding agents rather than editing one monolith.

The human collaboration feature sits inside the Actor, not beside it. The README says XAgent can follow your guidance while solving complex tasks and can seek your assistance when it encounters challenges. So the human is a resource the Actor can call on, which is a different design from a system that pauses for approval at fixed checkpoints. Neither approach is strictly better, but they fail differently: a call-on-demand model can stall waiting for input you did not expect to give.

ToolServer is the safety boundary, and it is also the operational cost

Every action the Actor takes goes through ToolServer, described as a docker container that provides a safe environment for XAgent to run. The tool list is broad on purpose. File Editor writes, reads and modifies files. Python Notebook runs Python interactively for validating ideas and drawing figures. Web Browser searches and visits pages. Shell executes any shell command, including installing programs and hosting services. Rapid API retrieves and calls APIs from Rapid API, with a pointer to the ToolBench project for the API collections.

Read that list again with the safety claim in mind. A shell tool that can install programs and host services, plus a browser, plus network API access, is a capable environment. The container is what makes it tolerable. The design choice is to give the agent real capability and put the fence around it rather than restricting the toolset. That is a defensible position, and it puts the burden on you to treat the container as the security boundary it is claimed to be: image provenance, what the container can reach on your network, and what persists after the run.

The README also states that you can add new tools to ToolServer. That is the practical extension path for most teams. Adding a tool means writing it into the container rather than granting the agent access to something on your host, which keeps the boundary intact.

Getting it running: docker compose, config.yml, and one run.py invocation

Setup is two stages. First the ToolServer. You need docker and docker-compose installed. Then either pull the image with docker compose up, or build from local sources with docker compose build followed by docker compose up. Add -d to run in the background. The README notes that when ToolServer is updated you must re-pull or rebuild, using docker compose pull or docker compose build respectively. There is a ToolServer/README.md for detail beyond this.

Second, XAgent itself. Python 3.10 or newer, then pip install -r requirements.txt. Configuration happens in assets/config.yml, and the README is direct about the model requirement: at least one OpenAI key, with gpt-4-32k highly recommended and gpt-4 acceptable for most simple tasks. At least one gpt-3.5-turbo-16k key should be present as a backup. The README states plainly that gpt-3.5-turbo is not tested or recommended because of its minimal context length, and that you should not try to run XAgent on it.

The run command is python run.py --task "put your task here" --config-file "assets/config.yml". There is an --upload-files argument for initial files. Output lands in local_workspace, and after execution the entire workspace from ToolServerNode is copied to running_records, which also holds intermediate steps such as task statuses, LLM input-output pairs and used tools. You can reproduce a prior run by setting record_dir in the config. One more config detail: to change the config file path for XAgentServer, edit the CONFIG_FILE value in the .env file and restart the docker container.

The context window is the hard constraint, not a tuning knob

The most concrete limitation in the README is the model requirement. Recommending gpt-4-32k and requiring a gpt-3.5-turbo-16k backup is a statement about how much context the agent consumes. Plans, subtask history, tool outputs, file contents and browser results all accumulate. The README's warning against gpt-3.5-turbo is not about quality, it is about length: minimal context length is the stated reason.

That has cost and availability consequences the README does not quantify. A system that prefers a 32k-context model is a system whose per-task spend scales with how much history it carries, and whose throughput depends on access to that model tier. If your organisation is standardised on a shorter-context model, XAgent is the wrong tool and the README says so directly. This is the clearest case where the documentation rules the project out for a whole class of users rather than leaving them to discover it.

A second limitation is structural. The README does not describe a sandbox escape analysis, a permission model inside the container, or a review step before shell commands execute. The safety claim rests on containerisation as a boundary. If your threat model includes the agent exfiltrating data it can read, or the container reaching services it should not, the README gives you no additional controls to reason about. Treat that as an open question to answer yourself, not as something the documentation settles.

How XAgent differs from a single-loop agent framework

The obvious comparison is a framework where one model loop calls tools directly, with no separate planner component and no container service. LangChain's agent executors follow roughly that shape: you define tools, the model chooses one, you execute it in your process, and the loop continues. The difference is not that one is better. It is where the structure lives.

In the single-loop design, planning is implicit in the model's next tool choice, and tools run in your Python process with your credentials and your filesystem. In XAgent, planning is a named component that produces and revises milestones, and tools run in a separate container reached over the network. That buys you a transcript with distinct planning artefacts, and it buys you a boundary around execution. It costs you a Docker dependency, a service to keep running, and a model with enough context to carry the plan alongside the working state. A team that wants an agent embedded in an existing application with its own permission checks will find the single-loop model easier to reason about. A team that wants the agent's execution environment to be disposable will find XAgent's split more natural.

Maintenance, releases and what Apache-2.0 does and does not settle

The release history is thin. The only release listed is v1.0.0, dated 22 November 2023. The repository is not archived and the last push is dated 31 July 2026, but there is no release cadence to plan around, and the README's own language, experimental and still in its early stages, should set expectations for API and config stability. The upgrade path documented for ToolServer is re-pull or rebuild the image, which is straightforward. For the Python side, the README gives pip install -r requirements.txt and no version pinning guidance, so dependency drift between your environment and the project's is something you will manage.

On licensing, Apache-2.0 is a permissive licence that permits commercial use and modification and includes an explicit patent grant. It also requires that you retain copyright and licence notices and state significant changes. That is a general description of the licence, not legal advice for your situation. Two things worth checking yourself: whether the models you point XAgent at impose terms that interact with your use, and whether the Rapid API tool pulls in third-party API terms through ToolBench. The README points at ToolBench for the Rapid API collections but does not discuss the terms attached to those APIs.

Who should run XAgent, and what to confirm on the first run

XAgent fits engineers who want to study or extend a planner-plus-actor architecture and who already run Docker. The extension points are named: new tools in ToolServer, new agents via the Dispatcher. The run artefacts are inspectable, with local_workspace for generated files and running_records for statuses, model input-output pairs and tool usage, plus record_dir for replaying a previous run. For that audience the project is legible and the boundaries are stated.

It does not fit teams without access to a long-context model, teams that cannot run a container with shell and browser access, or anyone who needs a stable interface with a release schedule behind it. The README's own warning against gpt-3.5-turbo is the fastest filter you can apply.

On a first run, confirm three things in order. That docker compose up starts ToolServer without errors and that the container's network reach matches what you intend. That assets/config.yml is accepted with your key set, including the backup model, since the README treats the backup as required rather than optional. And that the run produces the expected local_workspace and running_records contents, because those directories are how you audit what the agent actually did. If running_records does not contain the tool calls and model exchanges you need to explain a result, the safety story is harder to verify than the feature list suggests.

Editorial conclusion

Adopt XAgent if you have Docker, a GPT-4 or gpt-4-32k key, a backup gpt-3.5-turbo-16k key, and a task that benefits from a planner that revises its own milestones. Do not adopt it if you are limited to gpt-3.5-turbo, unwilling to run a container with shell and browser tools, or expecting a stable API: the repository labels itself experimental and its only listed release is v1.0.0 from November 2023. Before committing, verify that assets/config.yml accepts your key set, that docker compose up brings up ToolServer cleanly, and that a run writes the artefacts you expect into local_workspace and running_records.

Official sources

1. License: Apache-2.0
2. OpenBMB/XAgent on GitHub
3. Project website
4. README
5. Releases