agentops-open-course AGENTS.md

AGENTS.md

Guidance for coding agents working in the AgentOps Open Course. Humans should start with README.md. This repository dogfoods the AGENTS.md convention taught in Chapter 1.

Repository purpose

The course teaches the complete lifecycle of one Go AgentOps Agent with Google ADK, agentgateway, kagent, and OpenTelemetry into Tempo, Loki, Prometheus, Alertmanager, and Grafana. main is a completed executable reference learners inspect and extend, not a collection of illustrative snippets.

• agents/go/ is the Go reference agent, offline tests, state commands, protocol servers, and distroless image.
• agents/data/ is immutable seed input: SQLite, logs, runbooks, and runtime Agent Skills.
• evals/ is a standalone black-box Go evaluation module. It must not require or import the agent module.
• tools/ is a standalone Go module for repository conventions, accessibility, release evidence, and local support commands.
• content/ contains 84 Hugo pages: 74 course pages, nine chapter indexes, and the landing page.
• layouts/, assets/, data/nav.yaml, and hugo.toml own the Hextra site build and explicit learning path.
• skills/ contains portable Agent Skills distilled from the course, distinct from runtime skills under agents/data/skills.
• clients/web/ is a minimal dependency-free A2A client.
• load/ contains k6 load tests and documented latency budgets.
• infra/agentgateway/{host,k3d,gke}/ contains data-plane profiles.
• infra/k8s/base and infra/k8s/overlays/{local,gke} contain shared deployment resources.
• infra/kagent/ declares the BYO Agent, ModelConfig, and governed RemoteMCPServer.
• infra/observability/ contains host and in-cluster OpenTelemetry backends.
• infra/gcp/ is a plan-first OpenTofu module for the optional GKE laboratory.

The root go.mod exists only for the Hextra Hugo Module. Never add agent, evaluator, or repository-tool dependencies to it.

Course invariants

• Docs mirror source. Critical excerpts use {{< include >}} over exact named --8<-- [start:name] and end regions. Missing files, missing or duplicate regions, and empty excerpts fail the Hugo build.
• Seed and state stay separate. agents/data/incidents.db is never mutated. Host writes go to agents/go/.state; Kubernetes writers share agentops-agent-state.
• Only write-owning boundaries prepare state. A2A startup and direct state commands may copy or migrate runtime state. Probes and read tools remain read-only.
• Restore is crash-recoverable. Stop every writer first. State restore holds a process lock, fsyncs a three-phase journal, and recovers interrupted transactions before schema preflight or publication. Never bypass it with file copies or delete unexplained .restore-* evidence.
• Reads and writes have different authority. Only the conversational entrypoint can move its six read/runbook tools from local calls to MCP through AGENT_MCP_URL. Workflow and coordinator specialists keep local tools. Guarded writes remain in process.
• MCP cannot widen the surface. The client filters the server catalog through MCPReadToolNames; an advertised extra tool never joins the model request.
• Writes require confirmation and attribution. restart_service and resolve_incident require ADK confirmation, valid targets, approver/session/invocation identity, and a bounded redacted rationale. Mutation and audit insert share one transaction.
• Action replay is idempotent. The same invocation, action, and target returns the original audit result without another mutation.
• Policy is attached once. One ADK plugin at the app boundary covers every agent, sub-agent, workflow node, and coordinator specialist.
• Guard order is load-bearing. Before-model order is budget, compaction, redaction. The first non-nil callback result short-circuits later guards. After-model usage accounting runs before response redaction.
• PII has two layers. In-process deterministic Go redaction is always on. agentgateway adds central builtin masking and a private Go webhook that asks local Ollama for person, location, and organization spans. The webhook validates exact byte spans and fails closed.
• Layer 1 remains necessary. A gateway cannot see direct model calls, local logs, saved notes, audit writes, or pre-gateway chapters. It also cannot replace checksum-backed validation and credential tripwires.
• Skills and retrieved data have different trust. Only the locally constructed concrete skill loader can mark repository-reviewed instruction as trusted. Tool name strings cannot grant that status. Secret and PII redaction still applies.
• Audit is append-only, not immutable. SQLite triggers block ordinary update and delete, and every row carries its schema version. An administrator with file or schema authority can still alter it.
• Telemetry content stays private by default. ADK and GenAI content-capture settings default to literal false. Redaction covers model and tool boundaries, but raw session ingestion happens earlier.
• Collection and evaluation are separate. Runtime OTLP flows through the collector. evals exports only when EVAL_OTEL_EXPORTER_OTLP_ENDPOINT is set explicitly and forces child-agent export off.
• Evaluation is black-box. ADK REST and A2A events fold into one typed turn. Streaming partials never contribute duplicate usage. Expected domain values come from immutable seed data.
• Evaluation evidence is sanitized. Release artifacts and OTel attributes exclude prompts, answers, references, tool payloads, rationales, URLs, credentials, and provider errors.
• Build identity has one authority. Linker-owned mode, version, source identity, revision, tree digest, timestamp, and dirty state feed CLI output, AgentCard version, OTel resources, OCI labels, and backup manifests. Runtime environment variables cannot relabel a binary.
• Dirty work never claims HEAD. Release-bearing source resolution rejects tracked or untracked changes. Development may use unknown+dirty.<digest>, with revision empty and the deterministic tree digest recorded separately.
• Planning is bounded. The root agent plans multi-step investigations and verifies approved actions. The workflow is plan, investigate, evidence review, recommend; never introduce an unbounded reflection loop.
• Cost-efficient by default. Prefer deterministic offline tests, fakes, and the smallest model that materially proves the boundary. Do not start clusters, collectors, model servers, paid APIs, or cloud resources for an offline claim.
• Go coverage has a floor. mise run test fails when any package in agents/go or evals drops below 80% line coverage; scripts/check-coverage.sh measures it per package, because a repository total hides exactly the package worth worrying about. cmd/ packages are excluded by kind — they are package main composition wiring (flag parsing, dependency construction, process lifecycle) this project has chosen not to hold to the floor, and their coverage is measured like every other package's and simply sits below it. tools/ is maintainer scaffolding and sits outside the floor; only the accessibility driver is verified by execution rather than unit tests, because it needs a real Chrome, while internal/conventions is unit-tested as well as exercised by every mise run check, and the same script reports the module's real numbers on demand.