Introduction
AgentForge is a production-grade AI agent framework — the "Next.js for AI agents." Define business logic; the framework handles everything else.
Why AgentForge?
Most AI agent libraries leave you to build the hard parts yourself: state management, crash recovery, cost tracking, observability, multi-agent coordination. AgentForge owns the entire execution lifecycle so you can focus on what your agent should do, not how it runs.
Core Principles
- Own the loop, not the LLM — the LLM is a swappable dependency. Nothing is tied to one provider.
- State is sacred — zero data loss. Atomic state transitions. Checkpoint before proceeding.
- Reliability over features — 10 reliable features beats 50 unreliable ones.
- Observability is not optional — every decision, tool call, and token is always traceable.
Quick Example
import { defineAgent, defineTool, createLLM } from "@ahzan-agentforge/core";
import { z } from "zod";
const searchTool = defineTool({
name: "search",
description: "Search the knowledge base",
input: z.object({ query: z.string() }),
output: z.object({ results: z.array(z.string()) }),
execute: async ({ query }) => {
// Your search logic
return { results: [`Result for: ${query}`] };
},
});
const agent = defineAgent({
name: "assistant",
description: "A helpful assistant",
tools: [searchTool],
llm: createLLM({ provider: "anthropic", model: "claude-sonnet-4-20250514" }),
systemPrompt: "You are a helpful assistant. Use the search tool when needed.",
});
const result = await agent.run({ task: "Find information about AgentForge" });
console.log(result.output);Architecture
AgentForge is built in 7 layers, each building on the one below:
| Layer | Purpose |
|---|---|
| Execution Engine | Event-driven agent loop — plan, step, checkpoint, retry, rollback |
| Memory | Working (ephemeral), session (task-scoped), long-term (PgVector) |
| Tool Registry | defineTool() with Zod schemas, retry, caching, compensation |
| Autonomy Policy | Declarative trust rules enforced by the runtime |
| Multi-Agent Protocol | Handoff API with trust model and shared workspace |
| Observability | Full decision trace — every step, tool call, token, cost |
| Deployment | Persistent processes, serverless, queue-backed execution |
Next Steps
- Installation — set up your project
- Quickstart — build your first agent in 5 minutes
- Concepts — understand the mental model