agent-framework

An agent framework built for web applications, not laptops.

fg-agents (import package fg_agents) runs LLM agents inside a multi-user web product. Most agent frameworks — Claude Agent SDK, LangChain agents, AutoGen, CrewAI — quietly assume a laptop: a local filesystem to write to, a terminal to print to, and a single user who owns the machine. None of that exists in a web backend. There is no filesystem the agent may touch, there are many tenants whose data must never mix, replies have to stream to a browser over SSE, and sessions must survive server restarts.

fg-agents is a drop-in for FastAPI/Starlette that takes those constraints as the starting point. Out of the box you get SSE streaming, async persistence (PostgreSQL / SQLite / in-memory), multi-tenant isolation, and multi-agent orchestration.

The three things you bring

The framework is deliberate about what it does not do:

• Authentication — your app verifies users. You hand the router an authenticator that resolves each request to a tenant + user (AuthContext). The framework enforces tenant isolation on every access, but it never authenticates anyone.
• The model — there is no default model. You supply the API key and choose a "provider:model" string at runtime. OpenAI, Anthropic, Google, and ~20 OpenAI-compatible providers are supported, including local ones (Ollama, LM Studio, vLLM).
• The frontend — you build the chat UI; the framework streams typed events to it.

Brains, tools, lifecycle

Three ideas structure everything else:

• Brains — Orchestrator (planner / delegator / synthesizer) wrapping AgentEngine (the ReAct loop), driven by AgentLLM (the provider-agnostic client).
• Tools — @tool-decorated functions collected in a ToolRegistry; typed non-function tools (API, DB query, workflow, code) via handlers; and built-in self-management tools that replace the filesystem (objective, knowledge, skills, plan, notes).
• Lifecycle — session creation → ReAct turns (LLM → tools → LLM) → streamed StreamEvents → persisted messages → completion / cancel / resume, with middleware hooks at every stage.

No filesystem — by design

Where a laptop framework would give the agent CLAUDE.md and a scratch directory, fg-agents gives it repository-backed self-management tools: a persistent objective, named knowledge documents, reusable skills, a per-session plan and notes. Everything is keyed by scoped_agent_key(tenant_id, agent_id), so two tenants running the same agent never share a byte of memory. See Concepts.

Status

Distribution fg-agents, version 0.3.8 (pyproject; note fg_agents.__version__ still reports 0.3.0) · Alpha · Python ≥ 3.11 · 270+ tests · Part of the Fareground platform. The distribution and import names are the stable identifiers dependents rely on; the repository name (agent-framework) deliberately differs.

→ Start with Getting started · Concepts · API reference · Examples