agent-field/swe-af

SWE-AF Usage Guide

Autonomous engineering team runtime — one API call spins up coordinated AI agents to scope, build, and ship software.

What It Does

SWE-AF creates a coordinated team of AI agents (planning, coding, review, QA, merge, verification) that execute in parallel based on DAG dependencies. Issues with no dependencies run simultaneously; dependent issues run sequentially.

Installation

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Running

Terminal 1 — Control Plane:

af                  # starts AgentField on port 8080

Terminal 2 — Register Node:

python -m swe_af    # registers the swe-planner node

Triggering a Build

With local repo:

curl -X POST http://localhost:8080/api/v1/execute/async/swe-planner.build \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "goal": "Add JWT auth to all API endpoints",
      "repo_path": "/path/to/your/repo",
      "config": {
        "runtime": "open_code",
        "models": {
          "default": "zai-coding-plan/glm-5"
        }
      }
    }
  }'

With GitHub repo (clones + creates draft PR):

curl -X POST http://localhost:8080/api/v1/execute/async/swe-planner.build \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "goal": "Add comprehensive test coverage",
      "repo_url": "https://github.com/user/my-project",
      "config": {
        "runtime": "open_code",
        "models": {
          "default": "zai-coding-plan/glm-5"
        }
      }
    }
  }'

Configuration

| Key | Values | Description | |-----|--------|-------------| | runtime | "claude_code", "open_code", "codex" | AI backend to use | | models.default | model ID string | Default model for all agents | | models.coder | model ID string | Override for coder role | | models.qa | model ID string | Override for QA role | | repo_path | local path | Local workspace (new or existing) | | repo_url | GitHub URL | Clone + draft PR workflow |

Role-Specific Model Overrides

{
  "config": {
    "runtime": "open_code",
    "models": {
      "default": "zai-coding-plan/glm-5",
      "coder": "zai-coding-plan/glm-5",
      "qa": "zai-coding-plan/glm-5",
      "verifier": "zai-coding-plan/glm-5"
    }
  }
}

Available roles: pm, architect, tech_lead, sprint_planner, coder, qa, code_reviewer, qa_synthesizer, replan, retry_advisor, issue_writer, issue_advisor, verifier, git, merger, integration_tester

Multi-Repo Builds

SWE-AF supports coordinated work across multiple repositories in a single build. Pass config.repos as an array of repository objects, each with a repo_url (or repo_path) and a role. Single-repo builds remain backward compatible—just use repo_url or repo_path at the top level.

Complete Example: Primary App + Dependency

curl -X POST http://localhost:8080/api/v1/execute/async/swe-planner.build \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "goal": "Add JWT auth across API and shared-lib",
      "config": {
        "repos": [
          {
            "repo_url": "https://github.com/org/main-app",
            "role": "primary"
          },
          {
            "repo_url": "https://github.com/org/shared-lib",
            "role": "dependency"
          }
        ],
        "runtime": "claude_code",
        "models": {
          "default": "sonnet"
        }
      }
    }
  }'

Repository roles:

• primary: The main application being built. Changes here drive the build; failures block progress.
• dependency: Libraries or services that may be modified to support the primary repo. Failures are captured but don't block primary build progress.

Use Cases

• Primary App + Shared Libraries: Coordinate changes between a web application and its shared utilities/SDK.
• Monorepo Sub-Projects: Define multiple repos in a monorepo structure and orchestrate cross-package changes.
• Microservices: When a feature spans an API service and a worker service, define roles to manage interdependencies.

Requirements for open_code Runtime

1. opencode CLI installed and in PATH
2. Model provider credentials configured in OpenCode (e.g., OPENAI_API_KEY for z.ai)
3. Model ID format matches what OpenCode expects

Requirements for codex Runtime

1. Codex CLI installed and in PATH.
2. For ChatGPT subscription auth: run codex login on the host, set SWE_CODEX_AUTH_MODE=chatgpt or auto, and leave OPENAI_API_KEY unset for the agent process.
3. For OpenAI API-platform billing: set SWE_CODEX_AUTH_MODE=api_key and OPENAI_API_KEY.

Monitoring

# Check build status
curl http://localhost:8080/api/v1/executions/<execution_id>

Artifacts are saved to:

.artifacts/
├── plan/           # PRD, architecture, issue specs
├── execution/      # checkpoints, per-issue logs
└── verification/   # acceptance criteria results

What Happens in a Build

1. Planning — PM → Architect → Tech Lead → Sprint Planner (generates issue DAG)
2. Issue Writing — All issues written in parallel
3. Execution — Issues run level-by-level (parallel within levels)
   • Each issue: Coder → QA + Reviewer (parallel) → Synthesizer
   • Failures trigger advisor (retry/split/accept with debt/escalate)
4. Merge — Branches merged to integration branch
5. Integration Test — Full suite on merged code
6. Verification — Acceptance criteria checked against PRD

Key Endpoints

POST /api/v1/execute/async/swe-planner.build     # Full build
POST /api/v1/execute/async/swe-planner.plan      # Plan only
POST /api/v1/execute/async/swe-planner.execute   # Execute existing plan
POST /api/v1/execute/async/swe-planner.resume_build  # Resume after crash