AgentPlane

A Java/Spring Boot control plane for AI infrastructure and agent runtime workloads.

中文

AgentPlane provides the core backend primitives needed to register GPU/runtime workers, schedule agent tasks, track execution traces, persist runtime sessions, collect trajectory events, and export training-ready datasets. The project is intentionally backend-first: it focuses on control-plane contracts, reliability, observability, and data ownership before UI polish.

Features

• Worker registry for real GPU workers, simulated GPU workers, and agent runtime workers.
• Worker-pull task protocol for AGENT_TASK execution.
• Runtime provider registry for pluggable agent frameworks.
• Durable agent sessions, transcript mirrors, agent runs, events, and artifacts.
• Job lifecycle controls: idempotent submission, priority scheduling, cancellation, retry budgets, timeout reconciliation, and stale worker recovery.
• Trace records for job state transitions and agent runtime events.
• Dataset export filters for trainable telemetry and redacted content.
• File-backed state snapshots for local deployment and restart recovery.
• PostgreSQL-backed production state store through the prod profile.
• Docker Compose, Kubernetes manifests, and Helm chart for production deployment.
• GPU probe worker for validating real NVIDIA GPU nodes.
• Docker-ready Spring Boot service with health, readiness, liveness, and Prometheus endpoints.

Architecture

flowchart LR
  client["Client / Product App"] --> api["AgentPlane API"]
  api --> scheduler["Control Plane Scheduler"]
  api --> runtime["Runtime Plane"]
  scheduler --> workers["GPU / Agent Runtime Workers"]
  workers --> scheduler
  runtime --> store["State + Artifact Store"]
  workers --> traces["Trace / Trajectory Events"]
  traces --> datasets["Dataset Export"]

Loading

AgentPlane owns the infrastructure boundary:

• Control plane: workers, jobs, scheduling, retries, timeouts, cancellation.
• Runtime plane: providers, sessions, transcripts, runs, artifacts.
• Trace plane: task events, tool calls, safety checks, runtime telemetry.
• Data plane: exportable records for evaluation and future model or agent training.

Domain products, such as a healthcare or social assistant, should call AgentPlane through HTTP APIs instead of embedding scheduler or runtime ownership directly.

Quick Start

Requirements

• Java 17
• Maven 3.9+
• Docker, optional

Run Tests

mvn test

Run Locally

mvn spring-boot:run

AgentPlane starts on port 8080.

curl http://localhost:8080/actuator/health

Run With Docker

docker build -t agentplane-control-plane:0.1.0 .
docker run --rm -p 8080:8080 \
  -v /tmp/agentplane-state:/var/lib/agentplane \
  -e AGENTPLANE_CONTROL_PLANE_STATE_FILE=/var/lib/agentplane/control-plane-state.json \
  -e AGENTPLANE_RUNTIME_STATE_FILE=/var/lib/agentplane/runtime-state.json \
  -e AGENTPLANE_RUNTIME_ARTIFACT_ROOT=/var/lib/agentplane/artifacts \
  agentplane-control-plane:0.1.0

Run Production Profile With PostgreSQL

docker compose -f deploy/docker-compose.prod.yml up --build
AGENTPLANE_URL=http://127.0.0.1:18080 scripts/production-smoke.sh

Kubernetes

kubectl apply -f deploy/kubernetes/namespace.yaml
kubectl apply -f deploy/kubernetes/

The Helm chart is available at deploy/helm/agentplane.

API Examples

Register an agent runtime worker:

curl -X POST http://localhost:8080/workers/register \
  -H 'Content-Type: application/json' \
  -d @examples/curl/worker-register.json

Submit an agent task:

curl -X POST http://localhost:8080/jobs \
  -H 'Content-Type: application/json' \
  -d @examples/curl/submit-agent-task.json

Poll work from a worker:

curl -X POST http://localhost:8080/workers/{workerId}/tasks/poll

Export trainable dataset records:

curl -X POST http://localhost:8080/datasets/export/jsonl \
  -H 'Content-Type: application/json' \
  -d @examples/curl/dataset-export.request.json

More API details are available in docs/api.md.

Project Structure

agentplane/
  assets/                 Project icon assets.
  docs/                   Architecture, API, deployment, and development docs.
  deploy/                 Docker Compose, Kubernetes, and Helm deployment assets.
  examples/curl/          Minimal request examples.
  src/main/java/          Spring Boot application code.
  src/main/resources/     Runtime configuration.
  src/test/java/          MockMvc, persistence, scheduling, and reliability tests.
  workers/                Optional worker implementations and validation tools.
  scripts/                Smoke tests and operational helpers.
  Dockerfile              Container build.
  pom.xml                 Maven build.

Current Status

AgentPlane is an early-stage infrastructure project with a production-ready reference deployment for the current control-plane scope.

Implemented:

• Worker registration, heartbeat, resource reporting, polling, event reporting, completion, and failure.
• Runtime provider, session, transcript, run, artifact, and dataset APIs.
• File-backed local state and PostgreSQL-backed production state.
• Idempotency, retries, cancellation, timeout reconciliation, stale worker recovery, and priority scheduling.
• Structured API errors, readiness/liveness probes, Prometheus scrape output, and internal reconcile loop.
• Docker Compose, Kubernetes manifests, Helm chart, local tests, and production smoke scripts.
• NVIDIA GPU probe worker for real GPU-node validation.

Planned:

• OpenTelemetry trace projection.
• Real GPU inference workers for vLLM or SGLang.
• Multi-node scheduling benchmarks.
• Generated OpenAPI client packages.

Development

mvn test

The test suite covers API behavior, state persistence, scheduling, idempotency, retries, stale worker recovery, runtime session recovery, and dataset export.

See docs/development.md.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, and please keep changes focused, tested, and aligned with the control-plane boundary.

Security

Please report vulnerabilities according to SECURITY.md.

License

Apache License 2.0. See LICENSE.