Agent Forge (single-server prototype)

Agent Forge is a single-server agentic AI platform where agents can request creation and deployment of other agents, but only through strict policy gates. It’s designed to be minimal yet production‑minded: a clear separation between orchestration, policy, durable workflows, deployment, and runtime isolation.

This repository gives you a working prototype with:

• LLM backend: Ollama only
• Orchestration: LangGraph (Python)
• Durable workflows: Temporal (Python SDK)
• Policy gate: Open Policy Agent (OPA)
• RAG: Qdrant vector DB + simple ingestion
• Tracing/Evals: OpenTelemetry (Phoenix default)
• Sandbox: local fallback runner with strict allowlist (Firecracker stub)

---

What this platform does

1. Users submit objectives to the Gateway.
2. The Orchestrator (LangGraph) creates a plan and can request new agents via the Deploy Controller.
3. The Deploy Controller is the only component allowed to deploy agents. It calls OPA to authorize, then starts a Temporal workflow to build/evaluate/deploy.
4. Agents are deployed locally on the same server, either:
   • as systemd user services (preferred on Linux), or
   • as managed subprocesses (fallback).
5. Agents run as HTTP services on specific ports and can serve UIs or API endpoints.
6. Registry keeps track of running instances, ports, and status.

---

Architecture

User / Agent
   |
   v
Gateway (FastAPI) ----> Orchestrator (LangGraph) ----> Deploy Controller (FastAPI)
   |                           |                              |
   |                           |                              +--> Temporal Workflows/Activities
   |                           |                                       |
   |                           |                                       +--> Sandbox Runner (local fallback)
   |                           |                                       +--> Systemd user service or subprocess
   |                           |
   |                           +--> RAG Service (Qdrant)
   |
   +--> Telemetry (OpenTelemetry -> Phoenix OTLP HTTP)

---

Core services and technologies

Services

• Gateway (FastAPI)

  • User API
  • UI at /ui
  • Submits objectives and proxies requests to the orchestrator/deploy-controller

• Orchestrator (LangGraph)

  • Graph: objective → plan → decide_spawn → delegate → merge → decide_deploy → final
  • Can request spawn/deploy through Deploy Controller only

• Deploy Controller (FastAPI)

  • Only component allowed to deploy agents
  • Calls OPA
  • Starts Temporal workflows
  • Manages systemd/subprocess deployments

• Temporal Worker

  • Executes spawn/deploy workflows and activities

• RAG Service (FastAPI)

  • /ingest and /query
  • Uses Qdrant for vector search

• Sandbox Runner

  • Local fallback: allowlisted subprocess, timeouts, no network by default (best-effort)
  • Firecracker stub (interface only)

Technologies

• Ollama: LLM backend
• LangGraph: Orchestration graph
• Temporal: Durable workflows
• OPA: Policy enforcement
• Qdrant: Vector search
• OpenTelemetry + Phoenix: tracing

---

Repo layout

/README.md
/pyproject.toml
/config/
  config.example.yaml
  config.schema.json
/scripts/
  start_all.sh
  start_temporal_worker.sh
  deps_instructions.md
/services/
  /gateway/
  /orchestrator/
  /deploy_controller/
  /rag/
  /sandbox_runner/
/libs/
  /schemas/
  /policy/
  /telemetry/
  /common/
  /temporal/
  /llm/
/agents/
  /templates/
  /examples/

---

Ports (default)

Service	Port
Gateway (UI)	8000 (/ui)
Orchestrator	8001
Deploy Controller	8002
RAG Service	8003
Ollama	11434
OPA	8181
Qdrant	6333
Temporal	7233
Phoenix	6006
Doc‑RAG Agent	9010
Ops‑Triage Agent	9011

---

Requirements

• Python 3.11+ (3.10 works but 3.11 is recommended)
• uv for dependency management
• Local binaries for: Ollama, OPA, Qdrant, Temporal

---

Setup

1) Create config

cp config/config.example.yaml config/config.yaml

2) Install deps

make install

3) Start dependencies (manual)

Ollama

ollama pull mistral
ollama serve

OPA

./opa run --server --addr 127.0.0.1:8181 ./libs/policy

Qdrant

./qdrant --storage-path ./data/qdrant

Temporal (Temporalite recommended)

./temporalite start --ip 127.0.0.1 --port 7233

Phoenix (optional)

python -m phoenix.server.main --host 127.0.0.1 --port 6006

4) Start platform services

python -m tools.run_all

This starts:

• gateway
• orchestrator
• deploy_controller
• rag
• temporal worker

---

UI access

• Main UI: http://127.0.0.1:8000/ui
• Doc‑RAG agent UI: http://127.0.0.1:9010/
• Ops‑Triage agent UI: http://127.0.0.1:9011/

---

How the platform works

Spawn workflow

1. Gateway or agent submits SpawnRequest to Deploy Controller.
2. Deploy Controller sends request to OPA.
3. If allowed → Temporal spawn_workflow creates a registry entry and a capability token.
4. Response contains agent_instance_id.

Deploy workflow

1. Deploy Controller receives DeployRequest.
2. OPA authorizes.
3. Temporal deploy_workflow builds artifact and runs eval in sandbox.
4. If eval passes → systemd/subprocess deployment.
5. Registry updates with running status + port.

---

Scenarios

Scenario 1 — User submits objective

curl -s -X POST http://127.0.0.1:8000/objective \
  -H 'Content-Type: application/json' \
  -d '{"objective":"Build an ops triage agent","request_id":"11111111-1111-1111-1111-111111111111"}'

Scenario 2 — Spawn new agent

curl -s -X POST http://127.0.0.1:8002/spawn \
  -H 'Content-Type: application/json' \
  -d @agents/examples/spawn_request.json

Scenario 3 — Deploy agent

curl -s -X POST http://127.0.0.1:8002/deploy \
  -H 'Content-Type: application/json' \
  -d @agents/examples/deploy_request.json

Scenario 4 — Registry

curl -s http://127.0.0.1:8002/registry

Scenario 5 — Check workflow status

curl -s http://127.0.0.1:8002/workflow_status/<WORKFLOW_ID>

Scenario 6 — Stop an agent

curl -s -X POST http://127.0.0.1:8002/agent/stop/<AGENT_INSTANCE_ID>

---

Using the deployed agents

Doc‑RAG agent

Health:

curl -s http://127.0.0.1:9010/health

Query:

curl -s -X POST http://127.0.0.1:9010/query \
  -H "content-type: application/json" \
  -d '{"query":"What is this platform?"}'

Ops‑Triage agent

Health:

curl -s http://127.0.0.1:9011/health

Triage:

curl -s -X POST http://127.0.0.1:9011/triage \
  -H "content-type: application/json" \
  -d '{"issue":"Deploy failed with timeout","severity":"high","context":{"service":"gateway"}}'

---

RAG ingestion

Quick test

curl -s -X POST http://127.0.0.1:8003/ingest \
  -H "content-type: application/json" \
  -d '{"texts":["Agent Forge is a single-server agentic platform.","It uses Ollama, Temporal, OPA, and Qdrant."]}'

Ingest README

python - <<'PY'
import requests, pathlib
text = pathlib.Path("README.md").read_text()
resp = requests.post("http://127.0.0.1:8003/ingest", json={"texts":[text]})
print(resp.status_code, resp.text)
PY

---

Makefile commands

make install
make fmt
make lint
make test
make run
make worker
make check-ollama

---

Common troubleshooting

Agents return placeholder responses

• Restart systemd user services after code changes:

python - <<'PY'
import subprocess
subprocess.run(["systemctl","--user","restart","agent-<AGENT_ID>.service"])
PY

Agent port not responding

Check service:

python - <<'PY'
import subprocess
subprocess.run(["systemctl","--user","status","agent-<AGENT_ID>.service"])
PY

RAG returns empty matches

Make sure you ingested documents and that /query returns payloads.

OPA denies spawn/deploy

Update policy in libs/policy/policy.rego and restart OPA.

---

Assumptions

• Single server, trusted operator.
• File-based registry is acceptable for MVP.
• Sandbox runner uses allowlist + timeouts; OS‑level network isolation is TODO.
• Systemd user services are preferred; subprocess supervisor is fallback.
• Phoenix is default OTEL collector (OTLP HTTP).

---

License

MIT (or add your license)