Skip to content

ADR-016: Agent Runtime Scope, Tool Contract, and Side-Effect Safety

  • Decision status: Accepted
  • Implementation status: Not started
  • Applies to: Reference runtime, external targets
  • Date: 2026-06-16
  • Deciders: Grey Newell
  • Tags: agents, tool-use, safety, side-effects, evaluation, release-control

Context

RAGhelm's agent architecture includes substantial workflow work: production agent runtime, typed tools, internal API integrations, trajectory evaluation, reliability guardrails, memory, human-in-the-loop review, safety/policy/data governance, async execution, and synthetic business-agent demos.

ADR-001 defines RAGhelm's product spine as private RAGOps and release-control infrastructure. ADR-013 prioritizes evaluating external targets before broad internal backend/runtime abstraction. Therefore RAGhelm should avoid becoming a general-purpose agent framework before its release-control product object is stable.

The architecture still needs a concrete agent posture because the demo and roadmap include production-agent readiness.

This decision supports related implementation work without making issue numbers part of the durable architecture contract.

Decision

Use agent readiness evaluation as the product direction and a limited synthetic business-agent reference workflow as the demo/reference implementation.

In shorthand: C as product direction, B as reference/demo implementation.

RAGhelm's product role:

  • evaluate whether internal or external RAG/agent systems are ready to ship
  • collect agent trajectory evidence
  • score tool correctness, safety, cost, latency, completion, and escalation behavior
  • produce ReadinessScorecards and RAGRunManifests for agent releases

RAGhelm's reference implementation role:

  • provide a limited retrieval/business-advice agent target for demos and regression tests
  • demonstrate typed tools, budgets, traces, and human-review boundaries
  • avoid becoming a full general-purpose agent framework

Agent Target Architecture

External or reference agent target
  -> task/query input
  -> bounded plan/tool/retrieve/generate loop
  -> trajectory events and tool call records
  -> agent eval metrics
  -> RAGRunManifest
  -> ReadinessScorecard
  -> release gate: ship / needs_review / block

Tool Contract

Tools used by the reference agent or evaluated adapters must have typed contracts:

  • tool name and version
  • description and intended use
  • input schema
  • output schema
  • side-effect class
  • timeout and retry policy
  • idempotency requirements
  • permission/scope requirements
  • failure modes
  • redaction rules for logged inputs/outputs

Side-effect classes:

  1. read_only
  2. reads information without external mutation

  3. may run without human approval if authorized

  4. reversible_mutation

  5. changes external state but can be rolled back or overwritten

  6. requires idempotency key and audit event

  7. irreversible_mutation

  8. sends messages, spends money, deletes data, changes contracts, or causes hard-to-reverse effects
  9. requires explicit human approval unless a future ADR defines an approved automation policy

Safety and Budget Rules

Reference agents and evaluated agent targets must support or expose:

  • max step count
  • max wall-clock runtime
  • max tool-call count
  • max cost budget
  • timeout behavior
  • structured failure modes
  • no-answer/escalation behavior
  • human-review requirement for high-risk business-advice actions
  • trace/event output for every tool call

High-risk business advice should default to needs_review until policy, governance, and human-review flows are implemented.

Consequences

Positive

  • Aligns agent work with RAGhelm's release-control spine.
  • Keeps the synthetic business-agent demo compelling without overbuilding a general agent framework.
  • Supports external/internal agent evaluation through target adapters.
  • Makes tool safety, idempotency, budgets, traces, and human review explicit before side effects are automated.
  • Gives implementation agents clear boundaries for reference agent work.

Negative

  • RAGhelm will not initially be a full production agent runtime.
  • Some agent runtime issues become reference/demo or future work rather than core platform work.
  • External agent targets may not expose full trajectory evidence, reducing scorecard confidence.

Neutral / Trade-offs

  • A limited reference agent is still valuable because it proves the evaluation and release-control workflow.
  • Full async execution, memory, and human-review queues remain future architecture areas.
  • Agent trajectory evaluation can begin with normalized events even before all tools are production-grade.

Alternatives Considered

  1. Full production agent runtime

Pros: - Ambitious and impressive if complete. - Demonstrates deep agent implementation capability.

Cons: - Huge scope: tools, memory, HITL, safety, queues, evals, permissions, and deployment. - Risks turning RAGhelm into a general agent framework.

  1. Limited reference retrieval/business-advice agent only

Pros: - Strong demo and business-agent story. - Narrower implementation scope.

Cons: - Does not fully express RAGhelm's release-control value across external/internal agent systems.

  1. Agent readiness evaluator only

Pros: - Best fit with release-control product spine. - Avoids agent-framework sprawl.

Cons: - Less concrete for demos without a reference agent target.

  1. Agent readiness evaluator plus limited reference agent

Pros: - Best balance of product focus and demo clarity. - Lets RAGhelm evaluate agents while showing a concrete synthetic reference workflow.

Cons: - Requires disciplined docs so users understand the reference agent is not the whole product.

This is the chosen option.

Required Observability and Manifest Fields

Agent runs should record:

  • agent target ID and version
  • task/query ID
  • max step/time/cost budgets
  • tool schemas and versions used
  • tool calls with redacted inputs/outputs
  • side-effect class per tool call
  • idempotency keys for mutations
  • tool latency and failure modes
  • model/provider choices
  • retrieval evidence where applicable
  • escalation/human-review outcome
  • trajectory score fields
  • task completion result

Implementation Guidance

Initial implementation should:

  • define a minimal agent trajectory event schema
  • define typed tool contract models
  • implement read-only reference tools first
  • classify all tools by side-effect class
  • add step/time/cost budgets to the reference agent
  • ensure high-risk business-advice workflows produce needs_review unless reviewed
  • make agent trajectory evidence feed ReadinessScorecard and RAGRunManifest artifacts

Non-goals:

  • full autonomous side-effecting agent runtime in the first implementation
  • durable memory before tenant isolation is decided
  • irreversible tool actions without human approval
  • hiding incomplete trajectory evidence behind a passing scorecard

References

  • ADR-001: Product Architecture Spine for Private RAGOps Release Control
  • ADR-002: Release Readiness Scorecard and RAGRunManifest as Core Product Objects
  • ADR-013: External Target Adapters and Vector Backend Boundary