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_agent, k8s_health_agent, observability_agent, elasticsearch_agent, docker_agent, and ops_journal_agent 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 parallel subsystem checkers (one per enabled specialist's HealthCheck), 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, ALERTMANAGER_URL (default to their standard local dev ports) and LOKI_URL (optional: when unset the Loki tools are not offered)

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.

No external system is touched. Session- and user-scoped tools are unguarded because they only ever affect the caller; add_team_bookmark is the exception, because app-scoped state is the one place a single user's write reaches everyone else. Every collection is bounded: the session log keeps its most recent 200 entries (shared with ActivityPlugin), and notes (500 per user), preferences (50 per user) and bookmarks (100 per deployment) refuse writes past their limit rather than silently dropping records. Note ids are never reused. 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: