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. The lean core covers the engine, tools, and in-memory persistence; the web and postgres/sqlite extras add SSE streaming, the HTTP API, and durable persistence — plus multi-tenant isolation and multi-agent orchestration throughout. The entry point is one line: await ask("What's 2+2?") — no client object, model auto-detected from your environment. The usage ladder runs ask() → the Agent facade (multi-turn conversations, async with) → the low-level objects when you need middleware, skills, or a full web backend.

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.4.0, on PyPI (pip install fg-agents; fg_agents.__version__ reads it from package metadata) · Alpha · Python ≥ 3.11 · lean core (pydantic / structlog / aiohttp) · 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