Star 历史趋势
数据来源: GitHub API · 生成自 Stargazers.cn
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 modeHow the work gets done
DirectThe plan fixes the operations and their inputs. Tools carry them out without an intermediate model call.
LocalizedThe plan gives a model a specific job, such as writing a short processing script. Tools do the reading, writing, or computation.
ExtendedA model or agent can inspect a tool’s response and choose its next action within the permitted tools and session limits.

🚀 Quick start

📋 Prerequisites

  • Operating system: Linux x86-64
  • Python: 3.11 or higher
  • Tools: Git, Conda, and a running Docker Engine accessible to your user
  • Model services: A compatible LLM API and Embedding model services (Qwen3-Embedding-4B by default).

📦 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>"
ParameterMeaning
--query-fileFile containing the task request and expected deliverable; it must be inside the declared input directory.
--public-input-rootDirectory the task may read. Repeat this option for multiple separate input roots.
--run-dirNew or empty directory for this attempt’s logs and results.
--input NAME=PATHOptional named attachment inside a declared input root. May be repeated.
--network-policy declaredEnable 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 directoryUse it to
progress.logFollow the same guided stages seen in the terminal, including intermediate output previews.
pipeline.logInspect detailed requests, candidate scores, plan validation and runtime diagnostics. Use SGAR_CONSOLE=verbose to also show detailed diagnostic records live.
run_manifest.jsonCheck the final run status and the recorded cause of a failure.
delivery_manifest.json, when presentLocate the delivered output and verify its content hash.
experiment_report.mdRead the run report. Benchmark answer grading is a separate step.

🤗 Related Dataset

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.

SourceParent trajectoriesCanonical tasksSingle-loopAdjacent double-loopTotal episodes
SWE (swe_oracle)1,7631,7633,3151,5524,867
DeepMath (deepmath)9238311,6567332,389
ProofWriter (proofwriter)1,3921,0962,3159233,238
ZebraLogic (zebra)4894409054161,321
Total4,5674,1308,1913,62411,815

📚 Documentation

Start hereWhat you will find
Install & runDetailed example verification and preparation troubleshooting.
Environment & services · Model configurationLocal settings, model gateways, embeddings and tool dependencies.
Benchmark evaluationGAIA and Terminal-Bench entry points and scoring.
Resource catalog · Framework sourceResource declarations, orchestration and execution logic.
Third-party noticesAll 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

关于 About

Heterogeneous Resource Routing and Orchestration

语言 Languages

Python99.9%
Shell0.1%

提交活跃度 Commit Activity

代码提交热力图
过去 52 周的开发活跃度
1
Total Commits
峰值: 1次/周
Less
More

核心贡献者 Contributors