Cloud Agent Platform

English | 简体中文

Cloud Agent Platform turns natural-language tasks into recoverable, asynchronous Agent executions. It persists task state, iterates between LLM reasoning and tool calls inside isolated sandboxes, and returns the final result, workspace snapshot, and event stream.

Project goal: an operable, auditable, and scalable production-grade Cloud Agent Platform. Current maturity: pre-production. Every architecture, code, deployment, and validation artifact is evaluated against production invariants. Local smoke tests, Mock Eval, and template rendering are layered evidence—not the end goal or proof of production certification. The current release must not host public multi-tenant or arbitrary hostile workloads. Key blockers include secure repository ingestion, certification on target runsc nodes, observability, data protection, disaster recovery, and capacity validation.

See the production-readiness section of the system design for the complete status, acceptance criteria, evidence boundaries, and future evolution.

Production design principles

• Durable orchestration: PostgreSQL owns tasks, leases, retry eligibility, and the outbox; Redis is only a rebuildable low-latency dispatch pointer.
• Execution fencing: execution ID, generation, and lease prevent stale Workers from heartbeating, committing steps, or completing tasks.
• Recoverable execution: workspace checkpoints, durable SandboxHandle records, same-node Adopt, and finalization retry/dead-letter.
• Side-effect boundaries: ordinary workspace mutations converge through checkpoints; high-risk external actions require approval and the Action Journal.
• Verifiable sandboxing: Docker Engine SDK, resource and network limits, task-private tmpfs quota, post-start mount evidence, and a production runsc node-attestation gate.
• Narrow LLM seam: the platform owns llm.Client; OpenAI uses the official openai-go/v3 SDK and DeepSeek uses a dedicated Adapter. The Gateway owns first-call fallback, provider pinning, and usage admission.
• Long-running Agent guardrails: Registry-derived tools, token-aware compaction, windowed loop detection, in-flight cooperative cancellation, a recoverable empty-response nudge, and bounded large-output pagination.

Local engineering validation

Prerequisites: the Go version declared in go.mod, a working Docker daemon, Docker Compose, Bash, curl, and tar. The default uses the Mock LLM and requires no Provider credentials.

# Start dependencies, build the service, and run the local integration smoke.
# The script stops the server when it exits.
bash scripts/demo.sh

# Run deterministic Agent contract evaluation.
go run ./cmd/eval -format=markdown

# Verify the OpenAI and DeepSeek wire contracts offline.
bash scripts/demo_llm_providers.sh

# Stop the PostgreSQL and Redis containers when finished.
bash scripts/infra.sh down

demo.sh retains its legacy filename but is a local integration smoke test. It covers local directory import, task submission, idempotent deduplication, Redis dispatch, Docker execution, SSE, workspace download, and snapshot-based follow-up tasks. It validates protocol composition in the development topology; it is not production-environment certification. See .env.example for development configuration and the contribution guide for external-dependency test prerequisites.

Architecture overview

flowchart LR
    C[Client] --> API[API / SSE<br/>mTLS + RBAC]
    API --> PG[(PostgreSQL<br/>truth + RLS)]
    API --> Q[PG Queue<br/>Redis optional pointer]
    Q --> W[Worker]
    W --> D[Docker Engine<br/>runc / runsc]
    W --> L[LLM Gateway<br/>OpenAI · DeepSeek]
    W --> S[(Workspace Store<br/>Local / S3)]
    W --> PG

Loading

• The development topology uses PROCESS_ROLE=all, local identity, Mock LLM, and Docker/runc.
• The production topology permits only separate api and worker roles. Helm locks the startup contract through a bootstrap hook, external Secrets, mTLS, S3, the PostgreSQL queue, digest-pinned images, and runsc configuration.
• A production security gate means “reject startup when evidence is missing,” not “the target environment is certified.”

Current capabilities and key boundaries

The capability maturity matrix is the single source for implementation status, validation evidence, and production gaps. The unsupported claims section defines the scope of every capability statement.

Documentation

Goal	Document
Configure development environment variables or production values	.env.example and Helm values
Use the current HTTP/SSE API	API v0
Understand system protocols, production boundaries, and future evolution	System design
Deploy, upgrade, and troubleshoot	Operations and the Helm Chart
Review the threat model and trust boundaries	Security model
Contribute to the project	Contributing
Review AI provenance, LLM/Sandbox decisions, and validation rules	AI collaboration, architecture decisions, and engineering validation

Validation

Minimum local gates:

go mod verify
go test ./... -count=1
go test -race ./... -count=1
go vet ./...
go build -buildvcs=false ./...
scripts/verify_helm.sh

Docker, PostgreSQL, Redis, S3, and runsc tests have distinct prerequisites; SKIP does not mean PASS. See the validation levels and the system design's evidence rules.

Future evolution

Future themes are maintained only in the system design's future evolution section. The README does not duplicate priorities, phases, or timelines.

The project is intended to become production-ready; local smoke tests or a one-time validation run are never the completion criterion. AI is an engineering aid only. Maintainers retain ownership of architecture, risk acceptance, and release decisions; see the AI collaboration policy.