Quick Start¶

From nothing to a running, verified agent-utilities in a small number of minutes. This is the fast path; for the full config-complete walkthrough (secrets, profiles, multi-node) see the Self-Setup guide, and for the database environment see the pg-age recipe.

TL;DR — self-contained local GraphOS¶

pip install "agent-utilities[serving]"
setup-config generate --profile tiny
agent-utilities-doctor --only graph_identity auth
graph-os --transport stdio

That starts a durable knowledge graph and MCP server with no separately managed database or service. GraphOS supervises the packaged Rust epistemic-graph engine as an out-of-process child over a private local transport. Scale up later by generating the single-node-prod profile. The exact tiny, packaged-local stdio boundary uses a neutral in-memory bootstrap session, so it needs no IdP credential.

1. Install¶

pip install "agent-utilities[serving]"             # supported GraphOS runtime
# Optional external integrations compose by name, for example:
pip install "agent-utilities[serving,owl,postgresql,stardog]"

2. Generate the operator's config (all options)¶

Don't hand-write config.json — generate a complete, profile-seeded one that covers every option at a sensible default:

setup-config generate --profile tiny       # writes the XDG AgentConfig
setup-config reference                     # browse every option by subsystem

Profiles: tiny (local/edge), single-node-prod (one durable host), and enterprise (multi-node). Generated secret-bearing fields are blank. Persist runtime secret references only; do not place resolved credentials, tokens, certificate paths, or machine locations in the file.

For this tiny local stdio path, leave GRAPH_SERVICE_ENDPOINTS, KG_AUTH_TOKEN_REF, and KG_IDENTITY_OAUTH2 unset. GraphOS signs and validates a short-lived JWT with an in-memory key as a one-time proof, destroys the key and token, and returns a process-lifetime session; no user, host, endpoint, filesystem, credential, or proof data is persisted. Validate the boundary:

agent-utilities-doctor --only graph_identity auth

Every network transport, non-tiny profile, explicit engine endpoint, and other entry point requires exactly one external process identity source and its JWT validation policy. A configured-but-invalid source fails closed without local fallback. External stdio sessions remain bounded by a renewable shared expiry-only lease; identity drift is rejected and failed renewal cannot extend authority beyond the validated expiry.

3. (Optional) Databases — single-node-prod / enterprise¶

The tiny profile needs nothing here. For a durable Postgres tier (Apache AGE + pgvector + ParadeDB), run:

docker compose -f docker/pg-age-full.compose.yml up -d --build   # AGE + pgvector + pg_search

Then register it as a mirror connection and reconcile the existing graph into it — see databases recipe for the graph_configure calls (add_connection, mirror_status, reconcile). External SPARQL triplestore federation is owned by the epistemic-graph engine, not this repository.

4. Start¶

graph-os                       # MCP server; choose this for MCP clients
graph-os-daemon                # optional headless work host; no HTTP API
python -m agent_utilities      # agent + REST/API gateway; also hosts background work

5. Verify¶

Run the doctor — one sweep across config, engine, backend, secrets, auth, MCP fleet, hooks, and observability, each line carrying a fix + the skill that resolves it:

agent-utilities-doctor          # human-readable; --json for machines, --fix for safe auto-remediation, --live to probe endpoints

A HEALTHY (or WARNINGS) verdict + a graph_write/graph_query round-trip means the operator're up.

Use it¶

from agent_utilities import create_agent, create_agent_server

# Quick agent (skill_types selects which skill bundles to load)
agent = create_agent(name="assistant", skill_types=["universal", "graphs"])

# Full server uses the provider/model registry from AgentConfig.
create_agent_server()

See creating-an-agent.md for the complete agent walkthrough.

Console scripts (CLI reference)¶

Installed by the package:

Command	What it does
`setup-config {generate,doctor,reference}`	Generate the complete config.json, validate it, or list every option by subsystem
`agent-utilities-doctor`	Holistic deployment health sweep (`--fix`, `--live`, `--json`)
`graph-os`	The Knowledge-Graph MCP server (graph-os)
`graph-os-daemon`	Headless queue, maintenance, and background-work host (`--status`); no HTTP API
`agent-utilities-memory`	Memory store CLI
`python -m agent_utilities`	Start the interactive agent (flags: `--provider`, `--model-id`, `--mcp-config`, `--web`, `--port`)

Each command is also reachable over MCP/REST via the graph_configure tool (generate_config, config_doctor, system_doctor, …).