# Cooragent: Building Multi-Agent Workflows with Python

> Cooragent is a Python framework for generating agents and composing them into workflows. It fits developers who want LLM-backed planning, tool selection, and iterative workflow control, but its documentation leaves production behavior and rollback procedures unclear.

**LeapLabTHU/cooragent** — Official Repository of Cooragent.

- Repository: https://github.com/LeapLabTHU/cooragent
- Stars: 1,666 · Forks: 143
- Language: Python
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/leaplabthu-cooragent

## Cooragent's Two Agent Construction Paths

Cooragent addresses a specific development problem: assembling LLM agents requires choosing tools, writing prompts, deciding execution order, and coordinating several specialized agents. The project is aimed at developers who want to perform those steps through natural-language instructions rather than encode every workflow decision by hand. Its CLI and stored workflows are more relevant here than the hosted Agent Studio, which the README describes separately at `cooragent.com`.

The project exposes two task modes. Agent Factory begins with a description of the desired agent. According to the README, the system analyzes the request, uses memory and expansion to develop a fuller understanding of the need, selects tools through a Planner, polishes the prompt, and saves the construction work. The resulting agent can then be used or edited further. This route is best understood as generated configuration with a review stage, not as a deterministic agent compiler. The README does not explain what memory store is created, how much user context is retained, or how the generated agent is represented internally.

Agent Workflow starts from the target task rather than one agent description. A Planner selects agents with relevant expertise, plans their order, and sends work through a task distribution node. Each participating agent receives its own assignment. That makes Cooragent closer to a workflow generator built on LLM planning than to a normal fixed LangGraph application. The practical benefit is faster initial construction. The trade-off is that planner decisions can be difficult to predict unless the generated workflow is inspected.

## Launch, Polish, and Production Execution Modes

Cooragent divides workflow operation into three distinct modes. Launch Mode is intended for the first runnable version. The user describes the desired task, Cooragent analyzes it and selects agents. The README says that the completed workflow is saved locally, normally under `store/workflow`, which gives the user an artifact that can be reused or modified. In the CLI, this path starts with `run-l`.

Polish Mode is the control and revision stage. It permits direct editing of execution order, agent tools, LLM configuration, and prompts. It also accepts natural-language revision requests. The documented example asks the system to refine a stock analysis agent by replacing its browser tool with Tavily. According to the README, this can change prompts, tools, and other operational parameters. The CLI command is `run-o`.

Production Mode executes an already refined workflow with what the README calls reduced operational overhead. A Supervisor component checks output reliability and handles exceptions, and the associated CLI command is `run-p`. This label should be read carefully. The repository includes FastAPI and Uvicorn dependencies, but the README does not provide a production deployment guide, service configuration, authentication model, scaling procedure, or detailed Supervisor failure policy. It does not state how a workflow is promoted from `store/workflow`, nor does it document rollback. Production Mode is therefore a named execution path, not evidence that the repository supplies every control required for unattended production use.

## Installing Cooragent with uv and Python 3.12

The README requires Python 3.12 or newer, and `pyproject.toml` declares `requires-python = ">=3.12"`. The uv-based installation below creates the environment and installs the locked project dependencies. Clone the repository first, then create and activate the environment.

```bash
git clone https://github.com/LeapLabTHU/cooragent.git
cd cooragent
```

The next block installs Python 3.12 through uv, creates `.venv`, and activates it. The Windows activation path appears in the README as a comment.

```bash
uv python install 3.12
uv venv --python 3.12
source .venv/bin/activate   # For Windows: .venv\Scripts\activate
```

After activation, `uv sync` installs the dependencies represented by `uv.lock`. The browser support command is optional and should only be added when browser operation is needed.

```bash
uv sync
playwright install
```

Finally, create the environment file and start the CLI. Copy `.env.example` to `.env`, then add the LLM API keys, base URLs, and model settings required by the selected providers before launching it.

```bash
cp .env.example .env
uv run cli.py
```

The README does not show the CLI menu or a complete successful session. It gives an incomplete stock-agent command beginning with `run-l -t agen`, so that line is not sufficient to document a reliable first agent. For Windows, the installation guide also directs readers to `docs/QA.md` for additional dependencies.

## LLM Providers, Tools, and Environment Boundaries

Cooragent separates reasoning, basic, code, and vision-language model roles in `.env.example`. The example defaults the reasoning and basic model names to `qwen-max-latest`, the code model to `deepseek-chat`, and the vision model to `qwen2.5-vl-72b-instruct`. API keys and base URLs are present but commented out. That means installation alone does not provide working model access. The operator must add credentials and may also need to set compatible endpoints.

The declared dependency set shows that the framework is broader than a minimal prompt library. It includes LangGraph, LangChain integrations, `browser-use`, MCP adapters, the BeeAI framework, FastAPI, Uvicorn, SSE support, Pandas, NumPy, `yfinance`, plotting packages, document readers, and document writers. This supports varied agents, but it also expands the installation and upgrade surface. Exact transitive versions are not all pinned in `pyproject.toml`, although the repository contains `uv.lock`.

Tool access is configurable rather than unconditional. `USE_BROWSER=False` is the default because the README says the browser tool is time-consuming. Optional settings include `TAVILY_API_KEY`, `JINA_API_KEY`, `MCP_AGENT`, and `MAX_STEPS`. The default limit is documented as 25 steps. `ANONYMIZED_TELEMETRY` can control anonymous usage collection, and `SLACK_USER_TOKEN` is another optional integration.

The repository Dockerfile raises a separate operational concern. It embeds placeholder-looking API credentials and provider endpoints as `ENV` values, then copies `.env` into the image. It also configures internal network values and a regional Python package mirror. The Dockerfile appears tailored to that deployment context rather than being a neutral public template. A user should not copy those values into another environment without replacing placeholders and reviewing whether secrets belong in an image layer.

## Trade-offs Against a Fixed LangGraph Application

A fixed LangGraph application is the clearest alternative when task order, tool boundaries, and retry behavior are known in advance. That approach encodes nodes and edges directly in Python. It offers an explicit state schema, visible control flow, and code review around each transition. It also requires more initial design work when the workflow is exploratory.

Cooragent reverses some of that effort. Its Planner can select agents and construct a workflow from a task description, while Polish Mode permits either manual or natural-language revision. This is useful for prototyping unknown agent combinations or creating a starting point that can be stored under `store/workflow`. It is less appropriate when compliance requires a fully predetermined graph before execution, or when every planner decision must be reproducible from a reviewed source file.

The generated-versus-fixed distinction also affects failure diagnosis. In a fixed graph, an operator can inspect the transition that failed. With a generated workflow, the first step is to determine which saved configuration, planner result, prompt, tool response, and Supervisor action were involved. The README does not define that diagnostic chain. Teams needing detailed traces, explicit retry budgets, or deterministic routing should compare Cooragent's generated output against the control they would otherwise place directly in LangGraph.

## Maintenance Signals and Upgrade Work

The repository is not archived, and its last push was on 2026-04-29. The listed releases are `v0.1.1` from 2025-04-25, `v0.2.0` from 2025-05-07, and `v0.3.0` from 2025-06-13. The repository contains a `uv.lock`, test configuration, lint settings, and separate `dev` and `test` optional dependency groups. Those files provide useful inputs for an upgrade assessment, but the README does not document the release-to-branch mapping or an upgrade procedure.

There is also a version discrepancy that should be resolved before adoption. Recent releases include `v0.3.0`, while `pyproject.toml` declares `version = "0.1.0"`. The repository does not explain whether tags represent the project package, website, or another release stream. An installer should therefore verify which source revision corresponds to the release being evaluated instead of assuming that a tag and the package metadata describe the same version.

The Apache-2.0 license permits use, modification, and distribution under its conditions, including preservation of license notices and handling of warranty and liability provisions. This is a project metadata statement, not legal advice. Upgrade planning should also account for Python 3.12, the broad LangChain and LangGraph dependency range, browser and MCP integrations, and any provider-specific configuration. The repository supports `black`, and `pytest` is configured to collect `tests/` with coverage for `src/`, but no upgrade compatibility matrix is present.

## Conclusion

Adopt Cooragent if you want to prototype generated agents and inspectable multi-agent workflows through its Python CLI. Do not assume that its Production mode is deployment-ready without checking dependency pinning, credential handling, exception boundaries, and observability. Verify that `pyproject.toml` or the release you plan to install matches your intended API before integrating it.

## FAQ

### What is Cooragent used for?

Cooragent is an AI agent collaboration framework with an Agent Factory for creating individual agents and an Agent Workflow mode for selecting and coordinating multiple agents. It is intended for developers building agents and task workflows.

### How do I install Cooragent and start its CLI?

The README documents installing Python 3.12 with uv, creating a virtual environment, running `uv sync`, copying `.env.example` to `.env`, and starting `uv run cli.py`. API credentials and model settings must be configured before use.

### What is the difference between Cooragent's Launch, Polish, and Production modes?

Launch Mode generates a runnable workflow and normally saves it under `store/workflow`. Polish Mode revises its order, tools, LLM settings, and prompts, while Production Mode executes the refined workflow with a Supervisor handling output checks and exceptions.

### Does Cooragent require browser tooling during installation?

No. The README labels `playwright install` as optional. The browser tool is disabled by default with `USE_BROWSER=False` because it has a long wait time.

## Sources

- [Issues](https://github.com/LeapLabTHU/cooragent/issues)
- [LeapLabTHU/cooragent on GitHub](https://github.com/LeapLabTHU/cooragent)
- [License: Apache-2.0](https://github.com/LeapLabTHU/cooragent/blob/main/LICENSE)
- [README](https://github.com/LeapLabTHU/cooragent/blob/main/README.md)
- [Releases](https://github.com/LeapLabTHU/cooragent/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/leaplabthu-cooragent