ExecOrchestra README

项目的 README,来自 github.com/AgenticOrgLab/ExecOrchestra。合并为一个 markdown 文件:README.md。

ExecOrchestra

Heterogeneous Resource Routing and Orchestration

Coordinate tools, models, skills, and agents through executable plans.

Quick start  Documentation  View CoEvoke on Hugging Face

English · 简体中文

✨ Overview

ExecOrchestra is a heterogeneous resource orchestration framework for complex tasks. It combines tools, models, skills, and agents into executable workflows, allocating generative processing and direct execution as needed. Tools handle explicitly specified operations, while models and agents contribute where generation, judgment, or interaction is required. Clear execution records, intermediate artifacts, and delivered results help developers follow progress, diagnose issues, and extend their applications.

🧩 System framework

ExecOrchestra framework: task workflow, typed candidate construction across heterogeneous resources, and Direct, Localized, and Extended execution modes.

Organize heterogeneous resources around task requirements and determine the generative scope of each subtask.

Three execution modes

A plan gives the model as much control as the subtask calls for:

Execution mode How the work gets done
Direct The plan fixes the operations and their inputs. Tools carry them out without an intermediate model call.
Localized The plan gives a model a specific job, such as writing a short processing script. Tools do the reading, writing, or computation.
Extended A model or agent can inspect a tool’s response and choose its next action within the permitted tools and session limits.

🚀 Quick start

📋 Prerequisites

📦 Installation

  1. Clone the repository

    git clone https://github.com/AgenticOrgLab/ExecOrchestra.git
    cd ExecOrchestra/execorchestra
    
  2. Set the environment and install dependencies

    conda create -n execorchestra python=3.11 -y
    conda activate execorchestra
    python -m pip install torch==2.11.0 --index-url https://download.pytorch.org/whl/cpu
    python -m pip install -r requirements.txt
    python -m scripts.prepare_release init
    test -f .env || cp .env.example .env
    
  3. Build the Docker tool environment

    docker build -f sgar_mvp/docker/Dockerfile.runtime -t sgar-runtime:rc1 .
    python -m sgar_mvp.scripts.seal_rc1_runtime
    
  4. Prepare the embedding model service

    For local deployment, install the embedding environment and download the pinned model and tokenizer.

    conda create -n execorchestra-embedding python=3.11 -y
    conda run -n execorchestra-embedding python -m pip install -r requirements-embedding.txt
    python -m scripts.download_embedding
    

    Downloads are stored under .cache/embedding-model and .cache/embedding-tokenizer.

Using an existing embedding service instead

Skip the embedding environment and model-weight download above. Download only the matching tokenizer:

python -m scripts.download_embedding --tokenizer-only

In sgar_mvp/config/embedding_release.json, set runtime.api_endpoint_url to the full embeddings URL and runtime.api_model_id to its served model name. Keep runtime.tokenizer_path as .cache/embedding-tokenizer. The endpoint must use the configured Qwen3-Embedding-4B revision and return normalized 2,560-dimensional vectors.

🔑 Configuration

  1. Fill in API endpoints and keys

    Edit ExecOrchestra/execorchestra/.env. Replace the values below with your own; the file contains grouped comments for required and optional settings.

    LLM_BASE_URL="https://your-gateway.example/v1"
    LLM_API_KEY="your-model-api-key"
    SGAR_EMBEDDING_API_KEY="your-embedding-api-key"
    
    • LLM_BASE_URL / LLM_API_KEY: Your OpenAI-compatible model gateway and its access key.
    • SGAR_EMBEDDING_API_KEY: The embedding endpoint key. For local deployment, choose a private nonempty value; the service and client load the same .env.
  2. Load configuration into the framework terminal

    conda activate execorchestra
    set -a
    source .env
    set +a
    

    Repeat this step when opening a new framework terminal.

🧰 Runtime preparation

  1. (Optional) Start the local embedding service

    For local deployment, open a second terminal in ExecOrchestra/execorchestra. On a dedicated GPU server, choose an available GPU and run:

    conda activate execorchestra-embedding
    set -a
    source .env
    set +a
    export CUDA_VISIBLE_DEVICES=0
    export SGAR_EMBEDDING_DEDICATED_GPU=1
    export SGAR_EMBEDDING_MODEL_PATH="$PWD/.cache/embedding-model"
    python -m scripts.embedding_server
    

    The default endpoint is http://127.0.0.1:8001/v1/embeddings. Keep it running during preparation and task execution; stop it with Ctrl+C afterward.

  2. Prepare resources in the framework terminal

    python -m scripts.prepare_release all --allow-unavailable
    

    This command checks models, control roles, tools, and agents, prepares the usable resource pool, builds its index, and verifies configuration in that order. It makes live API/tool requests and may incur charges; it stops at the first failed stage. Unavailable candidates are recorded in sgar_mvp/runtime_state/preparation_report.json. Omit --allow-unavailable when every configured candidate must be available.

⚡ Run a task

After preparation succeeds, write your request to a UTF-8 text file and place it with any attachments in a dedicated input directory. Replace the placeholders:

bash scripts/run.sh \
  --query-file "<task-file>" \
  --public-input-root "<input-directory>" \
  --run-dir "<new-run-directory>"
Parameter Meaning
--query-file File containing the task request and expected deliverable; it must be inside the declared input directory.
--public-input-root Directory the task may read. Repeat this option for multiple separate input roots.
--run-dir New or empty directory for this attempt’s logs and results.
--input NAME=PATH Optional named attachment inside a declared input root. May be repeated.
--network-policy declared Enable declared network access for web tasks after configuring search/browser services. Tool network access is disabled by default.

The terminal displays each stage, selected resources, intermediate outputs, and delivery status. The same readable trace is saved to <new-run-directory>/progress.log. Check run_manifest.json for completion status and delivery_manifest.json for the delivered file path (delivery_locator, relative to the run directory).

Optional: run an example (XBench case 157)
bash scripts/run_xbench_demo.sh

This XBench DeepSearch-2510 task asks for the name of a coauthor of an XBench paper. The example shows how ExecOrchestra searches the web, checks the paper's author list, and delivers an answer with source links. Example details

View output files and log details
In the run directory Use it to
progress.log Follow the same guided stages seen in the terminal, including intermediate output previews.
pipeline.log Inspect detailed requests, candidate scores, plan validation and runtime diagnostics. Use SGAR_CONSOLE=verbose to also show detailed diagnostic records live.
run_manifest.json Check the final run status and the recorded cause of a failure.
delivery_manifest.json, when present Locate the delivered output and verify its content hash.
experiment_report.md Read the run report. Benchmark answer grading is a separate step.

CoEvoke (https://huggingface.co/datasets/Some-thy/CoEvoke) captures multi-agent collaboration across software engineering, mathematical reasoning, natural-language logical reasoning, and logic-grid puzzles. Each episode records agent messages, tool interactions, and intermediate review decisions, providing trajectory examples for analyzing coordination and training agents to work together.

Source Parent trajectories Canonical tasks Single-loop Adjacent double-loop Total episodes
SWE (swe_oracle) 1,763 1,763 3,315 1,552 4,867
DeepMath (deepmath) 923 831 1,656 733 2,389
ProofWriter (proofwriter) 1,392 1,096 2,315 923 3,238
ZebraLogic (zebra) 489 440 905 416 1,321
Total 4,567 4,130 8,191 3,624 11,815

📚 Documentation

Start here What you will find
Install & run Detailed example verification and preparation troubleshooting.
Environment & services · Model configuration Local settings, model gateways, embeddings and tool dependencies.
Benchmark evaluation GAIA and Terminal-Bench entry points and scoring.
Resource catalog · Framework source Resource declarations, orchestration and execution logic.
Third-party notices All involved content from other sources in this project.

👥 Contributors

TL-Z
TL-Z
WilsonWukz
WilsonWukz
ffcosmos
ffcosmos
Wuuu-uu
Wuuu-uu
hendrick-wang
hendrick-wang
huatl98
huatl98
inwt2333
inwt2333
LLLLLLsk0231
LLLLLLsk0231
cuixitong
cuixitong
qianc62
qianc62

🤝 Acknowledgments

Shanghai Artificial Intelligence Laboratory

ExecOrchestra (AgenticOrgLab/ExecOrchestra)

正在搜索数据库…

这是什么?ExecOrchestra 是一个面向复杂任务的异构资源编排框架。它将工具、模型、技能和智能体组合成可执行的工作流,并且只为每个子任务分配其所需的生成式处理。
它是框架还是库?它是一个框架。你需要打开框架终端,准备资源池及其索引,然后运行由 UTF-8 编码的请求文件描述的任务,该文件可以包含输入附件。
我要怎么让它运行起来?克隆仓库,配置环境并安装依赖,构建 Docker 工具环境,并准备嵌入模型。然后在 execorchestra/.env 中填写接口端点和密钥,在框架终端中加载配置,再运行准备命令。
我需要先安装什么?需要 Linux x86-64、Python 3.11 或更高版本、Git、Conda,以及一个正在运行且你的用户有权限访问的 Docker Engine。你还需要兼容的 LLM API 和嵌入服务,默认使用 Qwen3-Embedding-4B。
准备步骤会有费用或坑吗?准备步骤会发起实时的 API 和工具请求,因此可能产生费用。它会在第一个失败的阶段停止。除非你传入 --allow-unavailable,否则不可用的候选项会被记录在 preparationreport.json 中。
它是给谁用的?面向构建多步骤智能体工作流的开发者。执行记录、中间产物和交付结果可以帮助他们跟踪进度、诊断问题并扩展其应用。
执行任务时它能浏览网页吗?可以,但工具的网络访问默认是关闭的。配置好搜索和浏览器服务后,使用 --network-policy declared 运行,即可允许其用于网页任务。
需要 GPU 吗,还是只有嵌入模型需要?只有可选的本地嵌入服务需要 GPU,该服务适用于专用 GPU 服务器。你也可以让框架指向一个现有的嵌入端点,该端点需返回归一化的 2560 维向量。
子任务里模型能拥有多大的控制权?这取决于模式。Direct 运行固定操作,不调用模型;Localized 让模型编写一个简短脚本,由工具完成实际工作;Extended 让模型在检查工具响应后选择下一步动作,但需遵守会话限制。
运行过程中在哪里能看到发生了什么?阅读 progress.log 了解各引导阶段,阅读 pipeline.log 查看请求和计划诊断,阅读 runmanifest.json 获取最终状态和失败原因,阅读 deliverymanifest.json 获取交付文件的路径。
CoEvoke 数据集是什么?这是一个包含约 11815 个片段的数据集,记录了软件工程、数学、逻辑和逻辑网格谜题方面的多智能体协作,包括智能体消息、工具交互和审查决定。
它覆盖哪些基准测试?README 中提供了 GAIA 和 Terminal-Bench 的入口,并展示了一个 XBench DeepSearch 示例。基准答案的评分是单独的步骤。
大小
9.4 MB
星标
431
更新
提交Nov 18
时长
6天
提交 · 90 天