AgentForge

Building AI agents that reliably automate real-world software engineering tasks requires going far beyond simple prompt chaining. When scaling from local scripts to autonomous systems, agents require strict architectural boundaries, durable state management, human safety controls, and hermetic testing strategies.

AgentForge is an open-source AI agent framework built to automate software engineering workflows—mapping GitHub issues to verified pull requests while maintaining enterprise-grade architectural discipline.

Here is how AgentForge addresses the core engineering challenges of building production-ready AI agents 👇

---

1. Domain-Driven Design Over Layer-First Architecture

Many AI projects organize code strictly by technical layers (such as splitting code into controllers/, services/, and models/). AgentForge avoids this anti-pattern by implementing Domain-Driven Design (DDD) with bounded contexts as the top-level cut.

Each business capability maintains its own four-layer hierarchy:

• domain/: Contains pure entities, value objects, and business logic with zero external SDK dependencies or I/O operations.
• application/: Defines use case execution flows and abstract ports (interfaces).
• infrastructure/: Implements concrete adapters for external integrations like PyGithub, tree-sitter, LangGraph, PostgreSQL, and SMTP.
• interfaces/: Houses HTTP routers and webhook entry points.

The workflow_orchestration context operates as the aggregate root, coordinating use cases across issue intake, code search, fix generation, and pull request creation without leaking domain boundaries.

---

2. Durable State Machines & Human-in-the-Loop Safety

Autonomous agents can run into unexpected tool errors or multi-hour delays. AgentForge handles workflow orchestration using a LangGraph state machine backed by PostgreSQL checkpoints.

Key state and safety mechanics include:

• Explicit Lifecycle States: Workflows transition through defined states: analyzing → routing → awaiting_approval or awaiting_clarification → done or escalated.
• Durable Checkpointing: LangGraph stores full step-by-step workflow state after every graph node in PostgreSQL checkpoint tables, ensuring workflows survive system restarts or crashes.
• Two-Node Pause & Resume: When human sign-off is needed (REQUIRE_APPROVAL=true), the system executes a notify_approval node to send Slack or email notifications, followed by an await_approval node that triggers interrupt(). Side effects live strictly in the notification node so that resuming execution never triggers duplicate notifications.
• Automatic Guardrails: To prevent infinite loops, predefined guardrails enforce a maximum step budget (default 8 steps) and escalate workflows if compound tool failures occur (3 consecutive tool errors).

---

3. Vendor Agnosticism & Production Reliability

To remain resilient in production environments, AgentForge avoids tight coupling to specific LLM vendors or infrastructure setups.

• Unified LLM Port: All contexts interact with a unified LLMProvider port, allowing seamless switching between Anthropic, OpenAI, Ollama, and OpenRouter adapters.
• Runtime Configuration: Model names live outside environment variables and can be dynamically updated at runtime via PATCH /admin/model-config.
• Corrupted Checkpoint Recovery: If a state checkpoint becomes corrupted, the system automatically detects it and falls back to the last valid historical state.
• Stateless Horizontal Scaling: App instances are stateless because all state resides in PostgreSQL, allowing replicas to run behind a load balancer and resume any workflow.
• Observability: Execution decisions generate structured stdout JSON decision logs and export execution traces directly to LangSmith.

---

4. Testing Ground Rules: Fast, Hermetic, and Network-Free

Testing non-deterministic LLMs and external webhooks requires a disciplined testing strategy. AgentForge enforces strict testing ground rules:

• Zero External Network Calls: LLM adapters, GitHub APIs, and HTTP services are stubbed or faked at the port boundary using test doubles like FakeProvider, FailingProvider, and FlakyProvider.
• Capability-Based Layout: Test suites mirror the bounded-context layout, organizing tests by capability rather than code file locations.
• Graceful Database Probing: Database-backed integration tests probe PostgreSQL with a 2-second timeout and self-skip cleanly if Postgres is offline, ensuring unit tests pass instantly with or without Docker.
• Behavior-Driven Specifications: Gherkin feature files (features/*.feature) serve as executable specifications that map directly to implemented context tests.

---

5. Quickstart: One-Command Local Stack

AgentForge runs on Python 3.12+ managed by uv. You can launch the full local stack (PostgreSQL, automatic database migrations, and the FastAPI application) with Docker Compose:

# Clone the repository and start the full local stack
docker compose -f docker/docker-compose.yml up -d

By default, the container boots using local LLM models via Ollama so the entire stack runs locally without requiring API keys. Production deployments execute idempotent database migrations before starting stateless app instances serving on port 8000.

---

AgentForge demonstrates how classical software architecture principles—Clean Architecture, DDD, state persistence, and hermetic testing—can be applied to build reliable, enterprise-grade AI agents.