API reference

Import path: fg_agents. Symbols requiring optional extras (SQLiteRepository, PostgresRepository, AgentScheduler, ScheduleEntry, and the web symbols create_app / create_agent_router / AgentService / get_service / get_user_context) are import-guarded — they become None or raise on use when the extra isn't installed.

Core types

Enums

Key models

AgentDefinition(
    id, name, description, objective, system_prompt,
    model="",                       # required — no default
    fallback_models=[], tools=[], skills=[], knowledge=[],
    max_turns=50, max_llm_retries=3, min_turns=0,
    require_explicit_completion=False,
    max_tokens_per_turn=8192, llm_timeout_seconds=120.0,
    nudge_after_seconds=180, hard_deadline_seconds=600,
    temperature=0.0, middleware=[],
    sub_agents={},                  # dict[str, AgentDefinition]
    max_parallel_agents=5, memory_scope="isolated",
    extra_context, metadata,
)

• AgentSession — id, agent_id, user_id, tenant_id, parent_session_id, status, config, metadata, timestamps, token totals, total_cost_usd, turn_count, error.
• AgentMessage — id, session_id, role, content: str | list[dict], tool_calls, tool_call_id, tool_name, token_count, model, created_at, is_summarized; method .text().
• ToolCall — id, tool_name, arguments.
• ToolResult — tool_call_id, tool_name, output, status, duration_ms, error.
• ToolSchema — name, description, parameters.
• RegisteredTool — full tool definition: tool_type, parameters, json_schema, config, permission_level, timeout_seconds, retry_max, tags, handler; method .to_tool_schema(). Plus ToolParameterSpec.
• Skill — id, name, version, description, prompt_template, required_tools, config, tags.
• UserContext — user_id, tenant_id, org_id, metadata.
• ExecutionContext — runtime context passed to tools and middleware: session_id, agent_id, agent_name, turn_number, parent_session_id, user_id, tenant_id, metadata, working_memory, repository, active_skills; methods add_skill / remove_skill.
• LLMUsage, LLMStreamChunk, LLMResponse, SubAgentResult.

Also: scoped_agent_key(tenant_id, agent_id) — the tenant-namespacing key for persistent agent memory.

AgentEngine

AgentEngine(llm, tool_registry, repository, skills_manager=None, middleware=None)

async run(session_id, user_message, agent_def,
          metadata=None, variables=None) -> AsyncIterator[StreamEvent]
async cancel(session_id, cascade=True) -> int
.repository        # property

AgentLLM

AgentLLM(api_keys=None, custom_providers=None)

async stream_with_tools(messages, tools, model, system_prompt,
                        temperature=0.0, max_tokens=8192) -> AsyncIterator[LLMStreamChunk]
async complete_with_tools(...) -> LLMResponse

Model strings are "provider:model"; a bare string defaults to ollama. The module constant OPENAI_COMPATIBLE_PROVIDERS: dict[str, str] maps ~20 provider names to base URLs; custom_providers extends it.

Orchestrator & SubAgentRunner

Orchestrator(llm, tool_registry, repository, skills_manager=None,
             middleware=None, auto_register_builtins=True)

Auto-adds AuditMiddleware + TokenTrackingMiddleware, registers the built-in tools, and wires manage_agent to real delegation.

register_sub_agent(name, agent_def)
register_sub_agents(dict)
async initialize()
async run(session_id, user_message, agent_def,
          metadata=None, variables=None) -> AsyncIterator[StreamEvent]
async run_simple(user_message, agent_def, metadata=None) -> str
async cancel(session_id) -> int
async shutdown()
# properties: sub_agents, repo, tools, middleware, skills

manage_agent actions: spawn, spawn_parallel, message, report, get_report, status, list (task agents may only report / get_report).

SubAgentRunner(engine)

async run(task, agent_def, parent_session_id, context_data=None,
          metadata=None, on_event=None) -> SubAgentResult
async send_message(child_session_id, message, agent_def, ...) -> SubAgentResult

Tools

@tool(name=None, description=None, tool_type=ToolType.FUNCTION,
      permission_level="auto_approve", timeout_seconds=30, retry_max=0,
      tags=None, json_schema=None)

The decorated function gains .tool_definition (a RegisteredTool). Parameters named ctx / context typed ExecutionContext are auto-injected and excluded from the schema; sync functions are wrapped via asyncio.to_thread.

ToolRegistry(vault_resolver=None)

register(registered_tool)
register_function(fn)
register_many(fns)
unregister(name)
get(name); has(name)
get_schemas(names=None)
get_tools_for_agent(allowed)
async execute(tool_call, context) -> ToolResult   # timeout/retry, error detection,
                                                  # output normalization
.tools             # property

BUILTIN_TOOLS (the self-management tools: manage_objective, manage_knowledge, manage_skill, manage_plan, manage_notes, manage_context, manage_agent, session_complete, task_complete), dispatch_tool, and TOOL_TYPE_HANDLERS (handlers for API / DB_QUERY / WORKFLOW / CODE typed tools; CODE requires FG_ALLOW_CODE_EXECUTION=true and is not a sandbox).

Skills

SkillsManager(repository=None)

register(skill); register_many(skills)
get(id); resolve(ids); get_required_tools(skills)
# constructors
SkillsManager.from_markdown(...)
SkillsManager.from_dict(...)
SkillsManager.from_function(...)
await SkillsManager.from_url(...)
await SkillsManager.from_database(...)

Memory

WorkingMemory(session_id="", metadata=None)
store/get/has/remove/keys · add_finding · set_artifact/get_artifact
increment/get_count · tag/has_tag · get_context_for_llm(max_chars=8000) · clear

ContextManager(repository, trigger_fraction=0.80, keep_recent_fraction=0.15,
               custom_context_limits=None)

async build_context(session_id, system_prompt, model,
                    llm=None, force_compact=False) -> list[AgentMessage]

Helpers: estimate_tokens, get_context_limit. Health: ContextHealthConfig (thresholds: compress 0.40 · compact 0.80 · warn 0.85 · hard-stop 0.90), assess_health, compute_health_score.

Middleware

Middleware (Protocol) / BaseMiddleware (pass-through base) with hooks: before_llm_call · after_llm_call · before_tool_call (return None to block) · after_tool_call · on_turn_complete · on_error.

Implementations:

• AuditMiddleware(repository)
• TokenTrackingMiddleware(repository) + estimate_cost
• PermissionMiddleware(rules=None, default_level="auto_approve", denied_tools=None, approval_callback=None) with PermissionRule(tool_pattern, level, condition=None, reason="") — levels auto_approve / ask / deny / conditional; ask with no callback fails closed to deny
• RateLimitMiddleware
• LoopGuardMiddleware(config) + LoopGuardConfig
• ContextCompressionMiddleware(config) + CompressionConfig + progressive_compress

Persistence

create_repository(backend="memory", **kwargs)
# backends: "memory" · "sqlite" (db_path) · "postgres"/"postgresql" (db_url, echo)

BaseRepository (ABC) — abstract methods: initialize, close, create_session, get_session, update_session, get_sessions_for_user, delete_session, add_message, get_messages, mark_messages_summarized, log_tool_execution, save_artifact, get_artifacts, log_audit, get_audit_log, get_memory, set_memory, list_memories. Overridable defaults: clear_session_data, get_child_sessions, purge_old_sessions.

Implementations: InMemoryRepository, SQLiteRepository, PostgresRepository, Repository (alias), Base (SQLAlchemy declarative base).

Streaming

StreamEvent(id, type, session_id, data, timestamp, turn_number)
.to_sse()  ·  .to_dict()

Event constructors: session_started, turn_started, text_delta, thinking_delta, tool_call_event, tool_executing, tool_result_event, subagent_started, subagent_completed, context_compacting, turn_completed, session_completed

sse_response(request, events, heartbeat_interval=15)
# production SSE: heartbeat, disconnect detection, Last-Event-ID replay

Prompts

build_system_prompt(agent_def, skills=None, working_memory_context="",
                    extra_context="", variables=None, registered_tools=None,
                    knowledge_index=None, skill_index=None, objective=None,
                    plan=None, split_volatile=False)
load_knowledge(sources)
DEFAULT_SYSTEM_PROMPT · ORCHESTRATOR_SYSTEM_PROMPT · TASK_AGENT_SYSTEM_PROMPT

split_volatile=True separates byte-stable prompt sections from per-turn notes/plan to preserve provider prompt caches.

Scheduler

AgentScheduler(orchestrator, repository, agent_definitions,
               poll_interval_seconds=30, pre_execute_hook=None, post_execute_hook=None)

schedule_cron · schedule_once · schedule_on_event · trigger_event
cancel_schedule · list_schedules · get_schedule · update_schedule · delete_schedule
run_now · start · stop

Plus the ScheduleEntry model. Requires the scheduler extra (croniter).

App, router, service

create_app(agents, db_url=None, api_keys=None, tool_registry=None,
           cors_origins=None, prefix="/api/agent",
           title="Fareground Agent API", admin_only=True, **fastapi_kwargs) -> FastAPI

create_agent_router(orchestrator, agent_definitions=None, service=None,
                    admin_only=True, authenticator=None) -> APIRouter

Auth types: Authenticator = Callable[[Request], Awaitable[AuthContext]]; AuthContext(tenant_id, user_id, scopes, is_admin) with can_access_tenant; HeaderAuthenticator (trusted-proxy headers); UnauthenticatedAccess (dev-only shared admin tenant). FastAPI deps: get_service, get_user_context.

AgentService(orchestrator, agent_definitions=None) — framework-agnostic business logic behind the router: create_session, get_session, get_sessions_for_user, delete_session, clear_session_data, send_message (streaming; the run is owned by a process-wide RunRegistry and detached from the HTTP request — client disconnect does not cancel), subscribe_to_run, cancel_run, send_message_sync, get_messages, get_artifacts, get_audit_log, list_tools, register_tool, list_agents, get_agent, register_agent, get_agent_memories, set_agent_memory, health.

HTTP routes (prefix /api/agent): see the table in Getting started.

Errors

AgentFrameworkError
├── LLMError (provider, model, status_code, retryable)
│   ├── LLMRateLimitError (retry_after_seconds)
│   └── ContextOverflowError (tokens_used, token_limit)
├── RateLimitExceededError      # the framework's own budget — fail-closed
├── ToolExecutionError
│   ├── ToolNotFoundError
│   ├── ToolDeniedError
│   └── ToolTimeoutError
├── SessionError
│   └── SessionNotFoundError
├── MaxTurnsExceededError
├── SubAgentError
├── MiddlewareError
└── SkillNotFoundError