开源AI工作流

Prerequisites

• Docker Desktop
• Python 3.13
• UV
• LLM API key (Anthropic, OpenAI, or Gemini)

Prerequisites

• Docker Desktop
• LLM API key(s)
• UV

Quick Start: Run Your First Task

Estimated time: 30-60 minutes for first run

This quick start walks you through running a single task end-to-end using the provided example.

Copy example env files

cp environment/.env.example environment/.env cp agents/.env.example agents/.env cp grading/.env.example grading/.env

2. Run an Example

We provide two examples:

Option A: HuggingFace Benchmark Task (Recommended)

Run tasks from the mercor/apex-agents benchmark dataset with 480 professional services tasks.

cd examples/hugging_face_task
./run.sh

See examples/hugging_face_task/README.md for details.

Option B: Simple Task

A minimal example with a pre-defined task (find a gorilla image in a filesystem).

cd examples/simple_task
./run.sh

See examples/simple_task/README.md for a detailed step-by-step walkthrough.

Both scripts will: 1. Start the environment container 2. Populate the environment with the world snapshot 3. Configure MCP servers 4. Run the agent 5. Save the final snapshot 6. Run grading and display results

1. Set Up Environment Variables

```bash cd archipelago

Edit agents/.env and grading/.env with your LLM API key (at least one required):

The environment/.env can be left as-is for local development

```

Environment

The Environment is a headless gateway designed to run in a Docker container. It serves as a management layer for LLM agents, providing MCP server orchestration, data population from S3, and state snapshotting.

Features

• MCP Gateway: Hot-swappable gateway that routes requests to configured MCP servers. Supports dynamic reconfiguration of tools and resources.
• Data Management:
• Population: Download data from S3-compatible storage into local subsystems (/filesystem, /.apps_data).
• Snapshots: Create tar.gz archives of the environment state and stream them back to the client or upload directly to S3.
• Docker-First: Designed to run as a containerized service with health checks and lifecycle management.

API Endpoints

Configuration

The environment is configured via environment variables:

Example: Configuring MCP Servers

import requests

config = {
    "mcpServers": {
        "filesystem_server": {
            "transport": "stdio",
            "command": "python",
            "args": ["main.py"],
            "cwd": "./mcp_servers/filesystem_server"  # Must be a valid path in the container
        }
    }
}
requests.post("http://localhost:8080/apps", json=config)

After configuration, http://localhost:8080/mcp/ exposes an MCP server that agents can connect to.

For more details, see the Environment README.

Running the Environment

1. Navigate to environment directory:

   cd environment
   

1. Set Up Environment Variables:

   cp .env.example .env
   # Edit if needed (can be left as-is for local development)
   

1. Run with Docker Compose:

   docker-compose --ansi always --env-file .env up --build
   

The server will be available at http://localhost:8080.

1. Configure MCP Servers:

Once running, configure your MCP servers via the /apps endpoint:

   curl -X POST http://localhost:8080/apps \
     -H "Content-Type: application/json" \
     -d '{"mcpServers": {"my-server": {"transport": "stdio", "command": "python", "args": ["main.py"], "cwd": "./mcp_servers/my-server"}}}'
   

1. Connect an Agent:

Your LLM agent can now connect to the MCP gateway at http://localhost:8080/mcp/.

ANTHROPIC_API_KEY=sk-ant-...

or OPENAI_API_KEY=sk-...

or GOOGLE_API_KEY=...

Components