Capabilities — What an Agent Can Do¶

A concrete catalog of what agent-utilities grants an agent, each with a copy-paste snippet in library form and the equivalent MCP tool. All tools are exposed by the graph-os MCP server and mirrored 1:1 by the REST gateway (/api/...) — see Consumption Models.

Source of truth for the tool surface: agent_utilities/mcp/kg_server.py (the graph_*, ontology_*, object_* tools and ACTION_TOOL_ROUTES). The parity contract test (tests/unit/test_gateway_mcp_parity.py) keeps the MCP and REST surfaces in lockstep.

The tool surface at a glance¶

25 MCP tools, every one with an action-routed REST twin:

Group	Tools
Graph core (13)	`graph_query`, `graph_search`, `graph_write`, `graph_ingest`, `graph_analyze`, `graph_orchestrate`, `graph_configure`, `graph_context`, `graph_feedback`, `graph_goals`, `graph_message`, `graph_sessions`, `document_process`
Ontology (6)	`ontology_property_types`, `ontology_value_types`, `ontology_interface`, `ontology_function`, `ontology_derive`, `ontology_link_materialize`
Objects (4)	`object_edits`, `object_index`, `object_permissioning`, `object_set`
Connectors (1)	`source_connector`

The REST gateway mounts the same surface under /api: the 25 action-routed twins plus granular sub-routes (/api/graph/write/sdd, /api/graph/ingest/jobs, /api/sessions, /api/goals, …), alongside the fleet supervisory plane (/api/fleet/* — health/topology/pause/kill/approvals plus the correlation queries /api/fleet/trace and /api/fleet/touched), a granular typed OpenAPI surface for the ontology/object layer (/api/ontology/value-types/{name}, /api/ontology/interfaces/{name}, /api/objects/{id}, /api/objects/{id}/history, … — see gateway/ontology_api.py), the service dashboard (/api/dashboard/*, including daemon status/shards), and Prometheus GET /metrics.

Knowledge graph: store & recall¶

Add knowledge and query it back — no external DB required.

from agent_utilities.mcp import kg_server

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

# Query it
res = await kg_server._execute_tool("graph_query",
    cypher="MATCH (n:Service) WHERE n.tier='critical' RETURN n")

Capability	MCP tool	Action(s)
Write nodes/edges/memories	`graph_write`	`add_node`, `add_edge`, `store_memory`, `bulk_ingest`
Cypher / federated query	`graph_query`	`query`, `scope=federated`
Hybrid / semantic / analogy search	`graph_search`	`hybrid`, `concept`, `analogy`, `memory`, `discover`
Bitemporal "as of" recall	`graph_query`	`as_of=<ISO-8601>`

Ingestion: turn corpora into knowledge¶

# Ingest a directory, repo, or document set into the KG
await kg_server._execute_tool("graph_ingest", action="ingest",
    path="./docs", content_type="auto")

graph_ingest actions include ingest, corpus, jobs, job_status, distill, agent_toolkit, ingest_knowledge_pack, and backfill_platform_history (pass corpus_name=<platform> and target_path=<channel-or-room-id>). Documents become first-class Document+Chunk ontology objects with OWL semantics.

Document → atomic-triple extraction (KG-2.64/2.65/2.66). Turn a document, URL, or pasted text into (subject) -[predicate]-> (object) fact edges carrying evidence span, confidence, and tags — streamed live and deduped semantically. Use graph_ingest action=fact_extract (inline) or the GPU-slot-scheduled job actions extract_submit / extract_jobs / extract_status / extract_pause / extract_resume / extract_jsonl. The same surface is exposed at /api/enhanced/extract/* (SSE stream + JSONL) and rendered interactively in all three frontends. See Document → KG Fact Extraction.

Ingestion scales horizontally: the durable task queue is selectable via TASK_QUEUE_BACKEND (sqlite | postgres | kafka, fail-loud when an explicit backend is unreachable), Kafka kg_tasks messages are keyed for per-tenant/per-repo ordering, and the kg-ingest-worker console script joins the kg-ingest consumer group from any host. See Event Backbone — Ingest Task Queue Scale-Out.

Orchestration: spawn teams & swarms¶

# Decompose a goal into a coordinated team at runtime
await kg_server._execute_tool("graph_orchestrate",
    agent_name="researcher", task="Summarize Q3 incident trends")

graph_orchestrate delegates one named agent. Focused current surfaces own the rest: graph_agents (swarm, computer use, runtime orgs), graph_jobs (dispatch and status), graph_workflows (compile, execute, dispatch, inspect, export), graph_governance (approvals, vetoes, policy checks), graph_evolution, graph_rlm, and graph_domain_ops. Recursive nesting, circuit breakers, cognitive-scheduler quotas, and blast-radius scoping are built in (pillar 1).

Agent turns always dispatch through a session-partitioned durable queue (AgentTurnEnvelope) consumed by a stateless agent-dispatch-worker fleet on any host — per-session serial execution, crash-safe at-least-once claims, and worker placement visible at /api/fleet/topology. See Queue-Driven Agent Dispatch and the queue-dispatch walkthrough.

Descriptive BPMN process knowledge is executable too: compile_process lifts a process definition into an executable plan via the ProcessPlanCompiler (ORCH-1.41), gated by ontology validation on the execution path (AU-ORCH.execution.ontology-validation-execution-path), with run lineage written back to close the descriptive↔executable loop (ORCH-1.43). See the ontology-to-workflow example.

Memory & autonomous goals¶

# Launch a background goal loop (durable, resumable)
await kg_server._execute_tool("graph_goals", action="create",
    goal="Keep the incident KB current", session_id="ops-1")

graph_goals: create, list, iterations, cancel. graph_sessions: list, get, reply, cancel. Sessions, turns, and goals are durable and resumable across restarts — per-host SQLite by default, or one shared Postgres state store for the whole fleet via STATE_DB_URI (AU-OS.state.unified-durable-state-externalization, see State Externalization).

Ontology (Palantir-Foundry parity)¶

await kg_server._execute_tool("ontology_interface", action="list")
await kg_server._execute_tool("object_set", action="create",
    name="critical-services", filter='{"tier":"critical"}')

Tools: ontology_interface, ontology_value_types, ontology_property_types, ontology_derive, ontology_function, ontology_link_materialize, object_edits, object_index, object_permissioning, object_set, document_process. Full object/link/function/action layer over the same engine (pillar 2).

Analysis & reasoning¶

graph_analyze is the strict structural/operations surface: inspect, enrichment_coverage, process_writeback, placement_plan, infra_sweep, and security_scan. Analysis in other domains uses the focused tools: graph_code for code intelligence and blast radius, graph_evaluate for evaluation/causal/forecast work, graph_explain for grounded context, and graph_observe for trace analytics. The GraphOS-served graph_rlm wrapper provides long-context execution through AU's typed application operation. OWL/RDFS forward-chaining reasoning remains native to the Rust engine (reason() over the epistemic-graph client).

The legacy graph_research, graph_ops_causal, graph_mine, and graph_mine_deep wrappers are not part of AU's served tool universe. Native engine mining remains available through the engine's engine_mining modality; causal/evaluation work should use the supported analysis and evaluation surfaces.

Coding & task management (harness)¶

Beyond the graph-os surface, the agent harness gives coding agents the machinery to edit code reliably and drive long-horizon work:

Apply code edits — governed DevWorkspace edit_file, backed by the shared edit engine parses SEARCH/REPLACE blocks or unified diffs and applies them with fuzzy matching (so edits land despite whitespace drift) plus a reflection loop on failure. See Edit-Application Engine (CONCEPT:AU-ORCH.execution.robust-multi-format-edit).
PRD → task list — the harness MCP server (mcp/harness_server.py) exposes task_parse_prd, task_analyze_complexity, task_next, task_set_status, and task_scope: decompose a PRD into a durable, dependency-aware task list, score complexity, and pull the next actionable task (cycle-validated). Backed by SDDManager (CONCEPT:AU-ORCH.planning.sdd-task-ergonomics).
Repo-map skeleton — POST /api/codemap with {"skeleton": true, "max_tokens": N} returns a token-budgeted, importance-ranked code skeleton for context injection (CONCEPT:AU-ORCH.planning.repo-map-skeleton).

Identity & multi-tenancy¶

Every gateway request passes through server-minted identity (OS-5.14): JWT bearer tokens are validated and scoped into an ActorContext (agent_utilities/security/request_identity.py), permission checks fail closed, and engine connections authenticate with an HMAC shared secret. Unauthenticated requests are always rejected with 401 outside health probes. In sharded deployments the ambient tenant also drives graph placement (see below). Walkthrough: identity & JWT example.

The unauthenticated health exception is liveness only: the response is {"status":"ok"} with Cache-Control: no-store and contains no component, readiness, version, endpoint, or topology detail. Detailed operational health remains behind authenticated doctor and fleet surfaces. Only the explicit or identity-mapped kg:admin capability grants graph administration; a generic application role named admin does not.

Scale out: shards, workers, and one shared state store¶

When one host is not enough, every plane scales independently — all opt-in, all byte-for-byte unchanged at defaults:

Plane	Mechanism	Flag / entry point
KG engine	Engine-authoritative placement catalog routes tenant graphs to fenced MultiRaft groups	one stable coordinator in `GRAPH_SERVICE_ENDPOINTS`; optional strict `GRAPH_RAFT_GROUP_ENDPOINTS` map for group-specific endpoints
Ingestion	Kafka `kg_tasks` keyed partitions + `kg-ingest` consumer group	`TASK_QUEUE_BACKEND=kafka`, `kg-ingest-worker`
Agent execution	Session-keyed `agent_turns` queue + dispatch-worker fleet	`agent-dispatch-worker`
Gateway	Pre-forked workers, per-tenant token-bucket rate limiting, engine circuit breaker	`GATEWAY_WORKERS`, `GATEWAY_RATE_LIMIT`
Durable state	One shared Postgres store with SKIP LOCKED queue claims + advisory-lock daemon leadership	`STATE_DB_URI`

Deep dives: Engine Sharding · Gateway Scaling · State Externalization · sharding walkthrough.

Reactive supervision & fleet autonomy (Agent OS)¶

The REST gateway exposes a native fleet supervisor (no separate service): /api/fleet/health, /api/fleet/topology, /api/fleet/events, /api/fleet/pause, /api/fleet/kill, /api/fleet/approvals (+ /grant) — per-domain error rates, live topology (including dispatch workers), monitoring event ingress, blast-radius containment, and a mutation/risk approval queue. See pillar 5 and the agent-webui Fleet Supervisor view.

On top of the supervisor sits an opt-in autonomy control plane: every autonomous mutating action is gated by the ActionPolicy decision point (orchestration/action_policy.py, fail-closed, audit-logged; policies in deploy/action-policy.default.yml), driving the desired-state fleet reconciler, remediation playbooks, health-gated deploy watch with rollback, and the reactive autoscaler. See Fleet Autonomy, action-policy postures, and autoscaling signals.

Observability¶

With the optional metrics extra, the gateway serves Prometheus metrics at GET /metrics (agent_utilities_* series: requests, latency, rate limiting, engine calls/breaker state, engine shard reachability, ingest queue depth and consumer lag — also the autoscaler's default signals — dispatch queue/turns/ workers, and MCP child health). Each Rust engine shard exposes its own epistemic_graph_* series on its --metrics-addr listener. Catalog: metrics reference · observability example.

Expose your own tools as MCP¶

Any agent-packages/agents/* connector follows the same template (create_mcp_server() in agent_utilities/mcp/server_factory.py) and can run as a streamable-http container — see Day-0 and the ecosystem map. GraphOS's embedded gateway that aggregates the fleet is hardened per child: concurrency limits, session pools, restart-on-crash, circuit breakers, and a multiplexer_status health tool (AU-ECO.mcp.profile-differences-from-client, agent_utilities/mcp/child_resilience.py).

Full runnable examples: examples/reference_agent/ (basic_agent.py, graph_agent.py, knowledge_graph_agent.py, mcp_agent.py, memory_agent.py, protocol_agent.py) and the operational walkthroughs under documentation examples.