Agents overview¶

A quick tour of every agent shipped with the platform — what it does, the tools it exposes, and the role required to invoke the mutating ones.

For how agents are composed inside orrery-assistant, see ADR-003: Graph Workflow Inversion (which supersedes ADR-002). For how to build your own, see Adding a new agent.

At a glance¶

orrery-assistant¶

The root orchestrator. The interactive root is orrery_chat_agent — a chat-mode ADK 2.0 LlmAgent that keeps conversation history and routes each query to the right specialist via AgentTool. A separate graph Workflow (orrery_triage_workflow) provides the deterministic, parallel, bounded-loop incident-response pipeline for batch / scheduled runs (make run-triage). Both reuse the same node agents; see ADR-003.

Run it:

make run-dev  # ADK Dev UI on :8000
make run-cli  # Terminal REPL
make run-cli PERSIST=1 # Persistent sessions + memory (in-memory, or PostgreSQL via DATABASE_URL)
make run-triage              # Deterministic triage Workflow, one batch run

Exposed capabilities: - orrery_chat_agent (interactive root) — conversational LLM that routes to kafka_health, k8s_health, observability, elasticsearch, docker, and ops_journal via AgentTool, plus incident_triage_agent for a single-turn full sweep and LoadMemoryTool (model-invoked load_memory) for cross-session recall - orrery_triage_workflow (batch root) — health_join barriers the 5 parallel subsystem checkers, then triage_summarizer → journal_writer → triage_route - remediation_actor / remediation_verifier — closed-loop remediation subgraph that acts → verifies → retries up to 3 times via a verify_route state counter

kafka-health¶

Cluster monitoring via confluent-kafka's AdminClient. Clients are cached as module-level singletons to avoid per-call reconnect overhead.

Config: KAFKA_BOOTSTRAP_SERVERS=localhost:9092, KUBECONFIG_PATH (optional, for Strimzi tools)

Core tools — Kafka protocol:

Strimzi tools — Kubernetes control plane (backed by orrery_core.default_registry.StrimziDetector):

k8s-health¶

Kubernetes control-plane tooling via the official Python client. Uses in-cluster config when available, falls back to ~/.kube/config.

Config: KUBECONFIG_PATH (optional)

Operator-aware tools — backed by orrery_core.default_registry (Strimzi + ECK built in; pluggable for others):

observability¶

A unified interface to Prometheus, Loki, and Alertmanager. HTTP sessions are pooled.

Config: PROMETHEUS_URL, LOKI_URL, ALERTMANAGER_URL (all default to their standard local dev ports)

elasticsearch¶

Elasticsearch cluster operations, split across two surfaces: REST tools that speak the Elasticsearch wire protocol against a live cluster, and ECK tools that introspect the Kubernetes control plane (*.k8s.elastic.co CRs) via the operator registry. HTTP sessions and the Kubernetes client are pooled.

Config: ELASTICSEARCH_URL (default http://localhost:9200), ELASTICSEARCH_API_KEY or ELASTICSEARCH_USERNAME + ELASTICSEARCH_PASSWORD, ELASTICSEARCH_VERIFY_CERTS, ELASTICSEARCH_CA_CERTS, ELASTICSEARCH_HTTP_TIMEOUT, KUBECONFIG_PATH (optional, for ECK tools)

REST tools — Elasticsearch wire protocol:

ECK tools — Kubernetes control plane (backed by orrery_core.default_registry.ECKDetector):

docker-agent¶

Container inspection and lifecycle via the Docker CLI (subprocess). No Docker SDK dependency — works with whatever docker binary is on PATH.

Config: none — inherits the calling environment's Docker context.

ops-journal¶

Demonstrates ADK's four state scopes (session / user / app / temp). Not infrastructure-touching — used for incident notes, team bookmarks, and preferences that persist across sessions.

Config: none.

All tools are read/write on local session state — no external system is touched, so none are guarded. See Cross-session memory for how notes can outlive a single session.

Picking an agent¶

If you're writing a new workflow and need to decide which specialist(s) to call: