FlatAgents (Python SDK)

Define single-call LLM agents in YAML. Use this package when you want one structured call per agent, with optional MCP tools and profile-driven model configs. For orchestration, install flatmachines separately.

For LLM/machine readers: see AGENTS.md.

Install

pip install flatagents[litellm]
# or
pip install flatagents[aisuite]

Optional extras:

flatagents[validation] – JSON schema validation
flatagents[metrics] – OpenTelemetry metrics
flatagents[orchestration] – installs flatmachines and re-exports its APIs

Quick Start

from flatagents import FlatAgent

agent = FlatAgent(config_file="reviewer.yml")
result = await agent.call(code="...")
print(result.output)

Agent Config (YAML)

spec: flatagent
spec_version: "0.10.0"

data:
  name: code-reviewer
  model: "smart"     # profile name or inline dict
  system: "You are a careful reviewer."
  user: "Review this code: {{ input.code }}"
  output:
    issues: { type: list, items: { type: str } }
    rating: { type: str, enum: [good, needs_work, critical] }

Templates

system and user are Jinja2 templates with:

input.* from FlatAgent.call(**input)
model.* resolved model config (provider/name/etc)
tools and tools_prompt if MCP tools are configured

Output Schema

If data.output is provided, FlatAgents requests JSON mode and parses the response. Invalid JSON falls back to {"_raw": "..."}.

Model Profiles (profiles.yml)

spec: flatprofile
spec_version: "0.10.0"

data:
  model_profiles:
    fast: { provider: cerebras, name: zai-glm-4.6, temperature: 0.6 }
    smart: { provider: anthropic, name: claude-3-opus-20240229 }
  default: fast
  # override: smart

Resolution order: default → named profile → inline overrides → override.

Python behavior: FlatAgent auto-discovers the nearest profiles.yml next to the config file. If a parent machine passes profiles_dict, it is used only as a fallback (no merging).

Backends

Built-in backends:

LiteLLMBackend (default, litellm)
AISuiteBackend (aisuite)
Codex OAuth backend (codex)
GitHub Copilot OAuth backend (copilot)

Selection order:

backend argument to FlatAgent(...)
data.model.backend
FLATAGENTS_BACKEND env var ("litellm" or "aisuite")
Auto-detect installed backend (prefers litellm)

Codex and Copilot are explicit only (not auto-detected):

model:
  provider: openai-codex
  name: gpt-5
  backend: codex
  oauth:
    auth_file: ~/.agents/flatmachines/auth.json

model:
  provider: github-copilot
  name: gpt-4o
  backend: copilot
  oauth:
    auth_file: ~/.agents/flatmachines/auth.json

python -m flatagents.providers.openai_codex_login --auth-file ~/.agents/flatmachines/auth.json
python -m flatagents.providers.github_copilot_login --auth-file ~/.agents/flatmachines/auth.json

MCP Tools

Configure MCP in data.mcp and pass a MCPToolProvider implementation. The SDK does not ship a provider; you supply one (e.g., from aisuite.mcp). Tool calls are returned in AgentResponse.tool_calls.

Validation

from flatagents import validate_flatagent_config
warnings = validate_flatagent_config(config)

Logging & Metrics

from flatagents import setup_logging, get_logger
setup_logging(level="INFO")
logger = get_logger(__name__)

Env vars: FLATAGENTS_LOG_LEVEL, FLATAGENTS_LOG_FORMAT, FLATAGENTS_LOG_DIR.

Metrics (OpenTelemetry):

pip install flatagents[metrics]
export FLATAGENTS_METRICS_ENABLED=true

Optional Orchestration

If flatmachines is installed (flatagents[orchestration]), the FlatMachine APIs are re-exported from flatagents for convenience:

from flatagents import FlatMachine

Examples (Repo)

Specs

Source of truth:

Metadata

Release files for flatagents 4.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for flatagents 4.2.1
File	Size	Uploaded
flatagents-4.2.1.tar.gz	114.2 kB	Jun 2, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for flatagents 4.2.1
File	Interpreter	ABI	Platform	Reset
flatagents-4.2.1-py3-none-any.whl 140.6 kB Jun 2, 2026	Python 3	none	any	Details

Total release size: 254.8 kB

Release files / flatagents-4.2.1.tar.gz

Download URL	flatagents-4.2.1.tar.gz
Size	114.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`68b7f96b1de73a61e9e0890584113c39bcdac25251494f8a1c9f950b561e1629`
BLAKE2b-256 checksum How to use checksums	`037af3c6ddcea73ab4d9f779ffd100050c8d4af9913b48d02bb46aa2a2cf4c72`
Upload date	Jun 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.12`

Release files / flatagents-4.2.1-py3-none-any.whl

Download URL	flatagents-4.2.1-py3-none-any.whl
Size	140.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`513c0fcc9f0076d51beb945bf383ad072763ede5c5f39a5be95dddbf062da1fe`
BLAKE2b-256 checksum How to use checksums	`d36d1a01a9c4df5f1c244d31f08350e6269921a866a2a386611bf9d65fba69de`
Upload date	Jun 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.12`