Agent Utilities

Version: 1.16.0

New here? Read docs/start-here.md — one page: what this is, the three ways to use it, and the zero-infra knowledge graph. For AIs, llms.txt is the entry index. Full docs are published here.

🤖 AI agents — this repo is self-deploying. If you were pointed here to set it up: read the 🚀 Zero-to-deployed procedure in AGENTS.md, loop genesis.yaml, and run the agent-utilities-deployment skill (or agent-os-genesis for enterprise). Ask the operator one question — homelab or enterprise? — and take it from there.

🧰 Install the skills first — they unlock how to use everything else. Once agent-utilities is installed, run agent-utilities install-skills to drop the skill toolkit — including the agent-utilities skill-graph (the platform's own reference manual) plus the deployment/evolution/KG skills — into the calling agent tool (Claude Code, etc.) and the agent-utilities XDG skills dir, where agents auto-load them. With no flags it installs into every detected tool; --tool claude or --path <dir> targets one. agent-utilities-doctor flags it if the toolkit is missing.

🚀 Deploy in one command

Point yourself (or any agent) at this repo, or just run:

# macOS / Linux
curl -fsSL https://knuckles-team.github.io/agent-utilities/install.sh | sh

# Windows (PowerShell)
irm https://knuckles-team.github.io/agent-utilities/install.ps1 | iex

The installer checks your host, installs agent-utilities, drops the skill toolkit into every AI tool you have (Claude Code, Cursor, Codex, Windsurf, …), wires the knowledge-graph MCP server, and hands off to a guided deployment. Pick your shape:

curl -fsSL https://knuckles-team.github.io/agent-utilities/install.sh | sh -s -- --profile enterprise

→ Full procedure: Zero-to-deployed · manifest: genesis.yaml.

⚡ What it is

agent-utilities is a batteries-included harness for building Pydantic-AI agents that ship with a knowledge graph, orchestration, memory, and tools. The zero-infra default needs no databases or external services — the knowledge graph runs in-process. Use it three ways:

→ Full trade-offs: Consumption Models.

The 30-second mental model

All four surfaces talk to one gateway; the gateway owns one knowledge-graph facade; the facade fronts one engine — the authority (a fast Rust engine that does compute, cache, semantics, AND durable persistence). Writes fan out to optional durable mirrors. Everything below the gateway is shared — the surfaces are just different windows onto the same brain.

flowchart TD
    subgraph Surfaces["Four ways in"]
        WEB[agent-webui] & TUI[agent-terminal-ui] & GB[geniusbot] & IDE[Claude Code / Cursor]
    end
    Surfaces -->|REST / MCP| GW["graph-os MCP + REST gateway<br/>(identity · ActionPolicy · metrics)"]
    GW --> KG["KnowledgeGraph facade<br/>(ontology · routing · memory)"]
    KG --> ENG["epistemic-graph Rust engine — THE authority<br/>compute + cache + semantic + durable (MessagePack/UDS)"]
    ENG -->|async lossless fan-out| MIR["optional mirrors<br/>Postgres / pg-age · Neo4j · FalkorDB · LadybugDB"]
    KG --> OWL["OWL / SHACL · Fuseki<br/>semantics (local SPARQL over the engine)"]
    GW -. fleet events / autonomy .-> FLEET["reconciler · playbooks · autoscaler"]

⚡ 5-Minute Quickstart

pip install agent-utilities          # zero external *service* deps to start

Point it at any model provider (OPENAI_API_KEY, or a local vLLM/Ollama endpoint via .env), then create an agent — skills, tools, and the in-process KG included:

from agent_utilities import create_agent

agent, toolsets = create_agent(name="assistant", skill_types=["universal", "graphs"])
print(agent.run_sync("What can you do?").output)

Stand it up and verify — 3 commands, zero infra

setup-config generate --profile tiny     # complete config.json (every option)
graph-os &                                # KG MCP server — no database needed
agent-utilities-doctor                    # one health sweep across every subsystem

Scale up (--profile single-node-prod/enterprise), add Stardog + pg-age, or let Claude set itself up — all in the Quick Start and Self-Setup guides.

Use the knowledge graph natively — for free, no database

from agent_utilities.mcp import kg_server   # GRAPH_BACKEND=epistemic_graph is the default

# Add knowledge...
await kg_server._execute_tool("graph_write", action="add_node",
    node_id="svc:payments", node_type="Service",
    properties='{"team":"fintech","tier":"critical"}')

# ...and query it back — in-process, no server required.
res = await kg_server._execute_tool("graph_query",
    cypher="MATCH (n:Service) WHERE n.tier='critical' RETURN n")

→ The full capability catalog (search, ingest, orchestrate, ontology, memory) is in docs/capabilities.md; runnable code is in the reference agent.

Heads-up — this is two repos. The heavy graph compute lives in a separate Rust engine, epistemic-graph (reached out-of-process over MessagePack/UDS — no PyO3). agent-utilities ships a pure-Python client for it, so you don't need Rust to get started. Contributing? See CONTRIBUTING.md.

Table of Contents

• The Technical Novel: Narrative Journey
• Overview
• Key Features
• Intelligence Graph
• First Principles Architecture
• Concept Map
• Architecture & Orchestration
• Multi-Model Config & Secret Storage
• Installation
• Quick Start
• Creating an Agent
• Building MCP Servers
• API Documentation
• Documentation
• Contributing
• License

🧭 Roadmap & Vision

This section is aspirational direction, not shipped behavior — it's here so you know where the project is heading. For what works today, see Capabilities.

The direction beyond a single agent harness is distributed agentic evolution: agents that learn from their own failures (the harness-engineering pillar ships the evolution loop today) and, over time, contribute reusable breakthroughs — new skills, TeamConfigs, refined prompts — back to a shared knowledge graph so improvements compound across agents. The building blocks that exist now (unified KG, capability auto-activation, cross-agent protocols) are the substrate; the "agents improving each other at scale" end-state is roadmap.

Designed-but-not-yet-running roadmap items (designs/specs exist; do not expect these to work out of the box today):

• Media Generation & Transcription (CONCEPT:AU-ECO.toolkit.media-gateway-failure-path/4.31): Self-hosted image (flux.2 + Stable Diffusion 3.5), video (hunyuanvideo), speech synthesis (xtts), and transcription (faster-whisper) exposed as agent tools under the MEDIA_TOOLS gate — requires the corresponding self-hosted model services to be deployed.
• In-House Training Substrate: Fine-tune the framework's own open-weight models end-to-end — a deterministic reward/data engine, torch/PEFT SFT/DPO/GRPO trainers (data-science-mcp[training]), a pure-Rust loss/optimizer performance path (epistemic-graph), checkpoint→reliability-suite eval hooks, and a model-registry role deploy seam. Build-now / run-later on the GB10 (first run: OpenSeeker SFT).

Key Features

Grouped by what they do. Each line links to the deep-dive; the full catalog with every concept ID is in docs/guides/features.md.

🧠 Knowledge graph & memory — the zero-infra core. One engine — the authority (native Rust: compute + cache + OWL semantics + durable persistence; writes fan out to optional Postgres/pg-age, Neo4j, FalkorDB, LadybugDB mirrors) with Schema-Pack domain profiles (KG-2.22–2.37: zero-LLM typed-edge extraction, transitive/inverse OWL closure, bitemporal as_of recall) over a high-performance Rust compute engine (MessagePack/UDS, no PyO3; measured ~52 kB/agent — see the capacity model for the honestly-projected 100M figure). Benchmarked against a conventional stitched memory stack (separate vector DB + BM25 + app-level fusion, no KV cache, no warm-fork), this unified memory matches recall (1.000) while retrieving ~3.6× faster, reuses cross-modal context across an agentic fan-out with retrieval_calls == 1 instead of N (the crossmodal_fork warm-fork path), keeps writes read-fresh in ~26 ms (incremental, not full-rebuild), and survives a restart via a durable KV cold-tier (100% survival, >300× vs recompute) — full scorecard + reproduction in the Phase-2 benchmark report.

🗂 Ontology system (Palantir-Foundry parity, graph-native) — the structured layer. Objects, links, interfaces, value/property types, derived properties, functions, action types, durable edits, object sets & fine-grained permissioning (KG-2.26, 2.38–2.48) — OWL/SHACL-backed, reified many-to-many links, bitemporal edit history, exposed over ontology_* MCP tools and the web-UI Object Explorer. A vendor-neutral ArchiMate upper ontology makes ServiceNow↔ERPNext↔Camunda interchangeable in one query.

🔀 Orchestration & self-evolution — how work gets planned and improved. Spec-Driven Development, emergent architecture (capability auto-activation, TeamConfig coalitions), global-workspace attention over multi-agent waves, ontology-to-workflow execution (KG-2.52/53, ORCH-1.41–43: lift a descriptive process into an executable plan), and governed evolution-to-branch publication (AU-AHE.harness.failure-evolution–21: propose-only, governance + regression gated, never auto-pushed).

🏢 Enterprise integration (Company Brain) — getting your systems in. A document-source connector framework (ECO-4.25–4.32, AU-KG.ingest.mcp-tool-connector) — native Postgres/filesystem/REST/web-crawl, with every other system riding the ~58-server MCP fleet via the universal mcp_tool source — feeding the 6-layer Company Brain runtime (KG_BRAIN_ENFORCE: trust-decay conflict resolution, field-level survivorship, data ACLs + tenant scoping, human-correction→rule→eval feedback).

📈 Scale-out planes (all opt-in; default stays zero-infra) — how it grows. Externalized durable state (one STATE_DB_URI, AU-OS.state.unified-durable-state-externalization–18), tenant-sharded engines (HRW routing, AU-KG.sharding.tenant-partitioned-sharding-hrw/AU-OS.scaling.shard-topology-visibility-per), Kafka ingest scale-out (KG-2.55–57, fail-loud), queue-driven agent dispatch (ORCH-1.45), and gateway scaling + Prometheus /metrics (AU-OS.observability.no-op-without-metrics, per-tenant rate limits, circuit breakers, GATEWAY_WORKERS).

⚡ Inference & numeric acceleration (all opt-in) — reuse compute instead of recomputing it. KV-cache layering (vLLM → LMCache → epistemic-graph) — pool and dedup vLLM's KV cache into the engine so inference workers share prefill by token-hash: the universal LMCacheMPConnector (dense and hybrid Mamba/GDN) over an L1 CPU + L2 engine tier stack (EpistemicGraphL2Connector AU-KG.backend.lmcache-native-connector / EpistemicGraphKVBackend KG-2.306 → engine EG-185/186/187), steered per-execution by a dynamic KV-layering policy (ORCH-1.105: cache-worthiness scoring). Plus the numeric xp numpy-shim (agent_utilities/numeric/, AU-KG.compute.surface-analytics-program) — a numpy-compatible namespace that routes reductions/linalg/random through the BLAS/LAPACK-free epistemic-graph numeric kernel (Surface A of the engine's Analytics Program, AU-KG.compute.numeric-kernel). The kernel is the sole numeric backend (AU-KG.compute.numpy-scipy-drop): the shim is kernel-or-raise — numpy is removed from agent-utilities entirely (imported/declared nowhere) and survives only as the kernel's internal rust-numpy dependency.

🛡 Autonomy & governance — how it acts safely. A fleet-autonomy control plane (AU-OS.config.fleet-event-ingress, 5.24–27, 5.29: POST /api/fleet/events → fail-closed ActionPolicy gate → reconciler, remediation playbooks, health-gated deploy-watch + rollback, reactive autoscaler), server-minted identity & fail-closed permissioning (OS-5.14, JWT ActorContext, HMAC engine auth), enterprise mutation governance, and a hardened MCP fleet gateway built into graph-os (AU-ECO.mcp.profile-differences-from-client: on-demand fleet loading with per-child limits, circuit breakers, restart-on-crash).

Shipped but lightly documented (real code, importable today):

• Causal reasoning: structural-causal-model types, d-separation, and formal reasoning over KG subgraphs — agent_utilities/knowledge_graph/core/formal_reasoning_core.py.
• Skill compiler (CONCEPT:AU-ORCH.execution.parallel-engine-visualizer): compiles SKILL.md prose (+ optional references/team.yaml) into executable GraphPlan workflows — agent_utilities/workflows/skill_compiler.py.
• Evolutionary memory & aggregation (CONCEPT:AU-KG.memory.tiered-memory-caching): the self-curating CRUD insight/skill memory banks (agent_utilities/harness/evolving_memory.py) plus the global-workspace score→select→broadcast aggregation over multi-agent waves (agent_utilities/graph/workspace_attention.py).
• KG auto-routing: the strategy-based router (agent_utilities/graph/routing/ — fast-path, workflow-context, and policy strategies) backed by capability designation + reward write-back (agent_utilities/knowledge_graph/retrieval/capability_index.py).
• Reactive framework (CONCEPT:AU-ORCH.reactive.event-sourcing-ledger): graph-native event sourcing, dynamic behavioral dispatch, and multi-axis budget guardrails — agent_utilities/graph/reactive/.

📖 View the Comprehensive Feature List & Architecture Deep Dives

🗺 Concept Map

→ Full Concept Map: docs/concept_map.md — canonical concept registry. → Single Source of Truth: docs/concepts.yaml — machine-generated registry of every concept marker in code. → Concept Index: docs/overview.md — all pillars with descriptions and code paths.

Synthesized from concept markers in the codebase into 935 canonical concepts across 8 pillars.

This count and the table below are generated from docs/concepts.yaml by scripts/gen_docs.py. Do not edit by hand.

🏗️ Architecture & Pillar Reference

The detailed architectural diagrams and deep-dive documentation for agent-utilities have been moved to their respective Pillar documentation pages in /docs.

• 1. Graph Orchestration & Planning
  • Contains: First Principles Architecture, SDD Lifecycle, Execution Flow (Dynamic Multi-Layer Parallelism).
• 2. Epistemic Knowledge Graph
  • Contains: Graph-OS Native Ingestion Pipeline, MAGMA Reasoning Views, Persistent Task Tracking.
• 3. Agentic Harness Engineering
  • Contains: Self-Models, Evolution, Evaluation.
• 4. Ecosystem Peripherals
  • Contains: graph-os MCP Tools, Server Endpoints, MCP Loading & Registry Architecture.
• 5. Agent OS Infrastructure
  • Contains: Human-in-the-Loop Tool Approval, Process Lifecycle, Auth/Security.
• 6. GeniusBot Desktop Cockpit
  • Contains: Premium Systems Cockpit, swappable plugins tab matrix, sandboxed terminal widget, visual finance trading dashboard.
• C4 Architecture Diagrams
  • Contains: Ecosystem Dependency Graph, C4 Container Diagram, Cross-Pillar Data Flows.
• Memory Architecture
  • Contains: Multi-Timescale Memory, Memento Context Management, Observational Memory Bridge.
• Company Brain Runtime
  • Contains: the 6-layer model wired end-to-end — trust/conflict resolution & field-level survivorship, data permissions/tenancy/audit, feedback→rule→eval, retrieval budget, streams, KG_BRAIN_ENFORCE.
• Vendor-Neutral Enterprise Ontology
  • Contains: the canonical ArchiMate crosswalk, vendor adapters, code→capability realization, and virtual REST federation.
• Multi-Tenant graph-os over Streamable-HTTP
  • Contains: hierarchical org→user isolation, private-by-default + commons/markings sharing, the five isolation layers (identity → named-graph → scope/visibility → Postgres RLS → audit), tenant-scoped fleet, and the elastic per-tenant engine pool.

External Agent Discovery (mcp_config.json)

Register the platform in your IDE's mcp_config.json using the standard CLI pattern. Generate it with setup-config mcp (doctor-driven) — don't hand-write it. You only need one server: graph-os. It serves its own Knowledge-Graph/engine tools (always on) and is the MCP fleet gateway — it loads any other MCP server declared in its MCP_CONFIG fleet file on demand via the built-in find_tools / list_catalog / load_tools / unload_tools / multiplexer_status tools, so hundreds of fleet tools stay out of context until you ask for them. (The standalone mcp-multiplexer has been folded into graph-os — there is no separate multiplexer server anymore.)

Self-contained (zero-infra) — the engine ships in the same install

This is the default and the simplest: one uvx --from agent-utilities graph-os is a complete, fully-capable Knowledge Graph MCP server with no external services. The epistemic-graph engine is a base dependency, and the published wheel is already the full CPU build (MATURIN_FEATURES=full — compute/finance/datascience/mining/graphlearn/ reasoning, SQL/Cypher, redb-authoritative durability, security, and every wire protocol) with the epistemic-graph-server binary bundled. (The GPU/ROS2 full-extras layer is deliberately excluded — it needs an external CUDA/robotics toolchain, which would defeat "self-contained.") On first call graph-os autostarts and supervises a local engine over a private Unix-domain socket (EngineResolver, CONCEPT:AU-OS.deployment.engine-resolver-auto-provision), durable by default (redb persists to the XDG data dir, so an acked write survives a restart), and reference-counted idle-shutdown so it self-stops when the last client disconnects. No database, no daemon, no Docker — just the one stdio process:

{
  "mcpServers": {
    "graph-os": {
      "command": "uvx",
      "args": ["--from", "agent-utilities", "graph-os"],
      "env": {
        "AGENT_ID": "local-developer",
        "WORKSPACE_PATH": "${workspaceFolder}",
        "MCP_TOOL_MODE": "both"
      }
    }
  }
}

That is the whole thing — omitting ENGINE_MODE/ENGINE_ENDPOINT/EPISTEMIC_GRAPH_AUTOSTART selects the zero-infra path where graph-os provisions the engine itself. (Optional: GRAPH_SERVICE_PERSIST_DIR=/path to pin the durable store somewhere specific, or MCP_CONFIG to point at a fleet file so find_tools/load_tools can mount other *-mcp servers on demand.)

"Same process"? The engine runs out-of-process — an auto-spawned child over a private MessagePack/UDS socket, not an in-process PyO3 extension (that coupling was removed on purpose to stay GIL-free and horizontally scalable). It is nonetheless self-contained: one install brings the wheel + the epistemic-graph-server binary, graph-os owns its whole lifecycle (autostart → supervise → idle-stop), and it needs no external service. Each uvx … graph-os you launch is its own isolated, fully-capable instance with its own small durable engine. ([full-extras] — the engine's GPU/ROS2 layer — is deliberately not pulled: it needs an external CUDA/robotics toolchain to run, which would defeat "self-contained," and it is a wheel build variant, not a pip extra.)

Shared engine (split-storage / Keycloak-protected fleet)

To instead point many clients at one shared epistemic-graph node (e.g. a fast-NVMe host) and a Keycloak-protected *-mcp fleet, set the engine-connection + fleet-auth groups:

{
  "mcpServers": {
    "graph-os": {
      "command": "uvx",
      "args": ["--from", "agent-utilities", "graph-os"],
      "env": {
        "AGENT_ID": "local-developer",
        "WORKSPACE_PATH": "${workspaceFolder}",
        "MCP_TOOL_MODE": "both",
        "MCP_CONFIG": "${workspaceFolder}/mcp_config.json",

        "ENGINE_MODE": "remote",
        "ENGINE_ENDPOINT": "tcp://10.0.0.10:9100",
        "EPISTEMIC_GRAPH_AUTOSTART": "0",

        "MCP_CLIENT_AUTH": "oidc-client-credentials",
        "OIDC_ISSUER": "http://keycloak.arpa/realms/homelab",
        "OIDC_CLIENT_ID": "mcp-multiplexer",
        "OIDC_CLIENT_SECRET": "<from OpenBao: bao kv get apps/graph-os>",
        "OIDC_AUDIENCE": "agent-services"
      }
    }
  }
}

One server, graph-os — the standalone mcp-multiplexer is fully folded in via the built-in fleet loader (attach_fleet_loader), so there is no separate multiplexer entry anymore.

Shared instance vs single-user — same engine, same fleet. Interactive clients (Claude Code, opencode, agents) use the single-user stdio form above: each spawns its own local graph-os that performs the OIDC client-credentials flow (they can't mint the gateway JWT themselves). Deployed/service clients use the shared instance at http://graph-os.arpa/mcp. Both are the same graph-os where it matters — ENGINE_MODE=remote

• ENGINE_ENDPOINT point every client at the one shared engine, and MCP_CONFIG at the one canonical fleet list. See Consumption Models.

Env vars, by group:

• Core (always): AGENT_ID + WORKSPACE_PATH (per-workspace identity), MCP_TOOL_MODE (condensed|verbose|both), and MCP_CONFIG → your fleet file (the mcpServers map of every *-mcp server graph-os may mount on demand). Ask find_tools("<what you need>") then load_tools(servers=[...]) to pull fleet tools in live.
• Engine connection (split-storage / remote engine): ENGINE_MODE=remote + ENGINE_ENDPOINT=tcp://<engine-host>:9100 + EPISTEMIC_GRAPH_AUTOSTART=0 point graph-os at a shared epistemic-graph engine (e.g. the fast-NVMe node) instead of autostarting a local one. Omit all three for the zero-infra default, where graph-os autostarts a local engine.
• Fleet auth (only when the *-mcp fleet is Keycloak-protected): graph-os mints a Keycloak client-credentials bearer and attaches it to every child call — MCP_CLIENT_AUTH=oidc-client-credentials, OIDC_ISSUER (token endpoint auto-discovered), OIDC_CLIENT_ID, OIDC_CLIENT_SECRET (from OpenBao apps/graph-os — never commit it), OIDC_AUDIENCE. Eunomia enforces per-principal authorization server-side. Omit these for an unauthenticated local fleet.

Note: Model selection, routing logic, and system configurations are centralized in your XDG ~/.config/agent-utilities/config.json. Only local workspace paths, local agent IDs, or environment overrides remain in the environment.

Multi-Model Config & Secret Storage

All LLM providers, model registries, safety guardrails, and scheduler policies are managed centrally via the XDG-compliant configuration file at ~/.config/agent-utilities/config.json.

Every field in the config.json has a 1-to-1 environment variable override. The environment variables (detailed in .env.example) act as secondary overrides for all settings.

Minimal config.json

You only need to declare your model providers; every other field has a sensible default. A minimal working config:

{
  "chat_models": [
    {"id": "qwen/qwen3.6-27b", "provider": "openai", "base_url": "http://vllm.arpa/v1",
     "tools_enabled": true, "can_route": true, "can_kg": true}
  ],
  "embedding_models": [
    {"id": "nomic-embed-text-v2", "provider": "openai", "base_url": "http://vllm-embed.arpa/v1"}
  ]
}

Every config.json key maps 1-to-1 to an uppercase environment-variable override (default_agent_name → DEFAULT_AGENT_NAME). JSON has no comments — keep notes in the guides. The fully-populated production template (auth, secrets, routing, scheduler, OTEL/Langfuse, A2A, sampling) lives in docs/examples/config.json.

For comprehensive definitions and capabilities of specific variables, see the Configuration Guide and Local Secret Storage Guide. The authoritative per-flag inventory and audit (every KG_*/GRAPH_*/EPISTEMIC_* flag, its default, and whether it should exist at all) is docs/architecture/configuration.md.

Installation

Install via pip:

pip install agent-utilities

To install with all optional dependencies (including MCP servers, UI, and external graph backends):

pip install "agent-utilities[all]"

For more details, see the Installation Guide.

Zero-infrastructure by default

Out of the box, agent-utilities runs as a single self-contained install with no external service dependencies (no database or graph server to stand up; Python package dependencies still apply). The default knowledge-graph backend is epistemic_graph — the always-included Rust-native engine that is the one authority (compute + cache + semantic + durable persistence). No Postgres/Neo4j server is required to get started.

To add a durable PostgreSQL mirror in production (for interop/BI/DR), turn on fan-out and name the mirror — the engine stays the read authority and Postgres receives the replicated write stream:

export GRAPH_BACKEND=fanout
export GRAPH_MIRROR_TARGETS='["pg-age"]'
export KG_CONNECTIONS='[{"name":"pg-age","backend":"age","uri":"postgresql://agent:agent@localhost:5432/agent_kg"}]'

Deployment

Full deployment instructions — running graph-os (the KG server + built-in MCP fleet gateway) as a standard stdio or streamable-http server, the centralized REST API gateway, Docker composes, and production hardening — are in the Deployment Guide. The flagship Deployment Configurations guide walks every shape from the zero-infra laptop default to a sharded, queue-driven, policy-governed fleet (STATE_DB_URI, GRAPH_SERVICE_ENDPOINTS, TASK_QUEUE_BACKEND, AGENT_DISPATCH_BACKEND, GATEWAY_WORKERS).

Already deployed and want to turn the enterprise/autonomy capabilities on? They ship off-by-default so the laptop experience stays zero-infra. The Enterprise Enablement Runbook is the ordered push → deploy → flag-enablement sequence (security → state → sharding → brain → autonomy), each stage independently reversible and verified.

Serving thousands of tenants over streamable-HTTP? The Multi-Tenant graph-os architecture covers hierarchical org→user isolation, private-by-default sharing with explicit commons/markings promotion, full tenant-stamped audit, and the elastic per-tenant engine pool — with ready-to-edit k8s and Swarm manifests in deploy/.

Quick Start

You can quickly launch the graph-os MCP server (a thin FastMCP wrapper):

uvx --from agent-utilities graph-os                       # stdio (default)
uvx --from agent-utilities graph-os --transport streamable-http --host 0.0.0.0 --port 8004

Or start the standalone agent from your code:

from agent_utilities.core.config import config
from agent_utilities.agent.factory import create_agent

# Configuration is automatically loaded from config.json
agent = create_agent(name="MyAgent")
response = agent.run_sync("Analyze the knowledge graph for recent updates.")
print(response.data)

For a comprehensive walkthrough, see the Quick Start Guide.

📚 Guides & Tutorials

For detailed tutorials, installation options, and configuration guides, refer to the docs/guides/ directory:

• Quick Start
• Installation Guide
  • Bare-metal, pip packages, Docker
• Deployment Guide
  • Zero-infra default, graph-os (KG + built-in fleet gateway, stdio/streamable-http), API gateway, production hardening
• Configuration & Environment Variables
  • Multi-tiered LLM setup, Models Config; the per-flag audit lives in docs/architecture/configuration.md
• Local Secret Storage (Vault & SQLite)
• Creating an Agent
• Building MCP Servers & API Wrappers
• API Documentation & Swagger

🌌 The Technical Novel

[!NOTE] Prefer a story to config tables? The Immersive Narrative Journey (docs/journey.md) traces agent-utilities live through the lifecycle of a high-stakes quantitative rebalancing mandate — a guided tour of the whole platform in motion.

Documentation

Comprehensive system documentation is available in the docs/ directory:

New to the project? Start with the Concept Overview Map to get oriented.

Core References

Pillar Deep-Dives

Contributing

Contributions are welcome. Please follow these guidelines:

1. Fork the repository and create a feature branch.
2. Write tests for new functionality — all tests must include assertions.
3. Follow existing patterns — use the established Pydantic models, structured prompts, and concept markers.
4. Run the test suite before submitting: uv run pytest tests/ -q.

   Note: All tests are strictly bounded by a 60-second timeout via pytest-timeout. Any test that sleeps or hangs indefinitely will fail automatically. Ensure you don't use time.sleep without bounds.

5. Update documentation in docs/ if your changes affect public APIs.

See AGENTS.md for project-specific conventions and architecture rules.

License

This project is licensed under the terms specified in the LICENSE file.