Beyond Logging: Implementing Declarative Contracts for LLM Agent Reliability

Why Your LLM Agent Needs Contracts, Not Just Logs

DEED is a declarative contract layer that enforces state invariants and policies between LLM pipeline definitions and executors. It prevents silent state drift by rejecting steps that violate pre-defined predicates, such as missing data or exceeded token budgets.

Why This Matters

Traditional observability tells you what occurred but fails to capture what was allowed to occur, creating a gap in high-stakes agent pipelines where state drift at step one might only surface as a crash at step three. By moving assertions out of Python code and into a declarative contract layer, teams can implement systematic error handling, checkpointing, and automatic credit refunds, transforming agents from unpredictable black boxes into auditable systems that prevent side effects before they execute.

Key Insights

• DEED enforces policies before LLM calls execute, allowing constraints like “cap budget_tokens <= 3000” to be enforced at the runtime level (2026).
• Declarative contracts using the .dd format enable checkpointing and idempotency keys to prevent duplicate side effects during pipeline replays.
• The DEED runtime is designed for safety-critical workflows, such as the mushroom_safety pipeline, to identify exactly which invariant failed two hops before a crash.

Working Examples

A DEED contract definition enforcing token caps and state pre-conditions.

agent score_agent
description "ICP scoring agent — evaluates company fit 0.0-1.0"
capabilities ["score_company"]
policy
  cap budget_tokens <= 3000
  allow score_company if enriched
contract score_contract
  pre enriched
  post scored
observe
  trace true

A pipeline specification with explicit stage-level error handling and checkpointing.

pipeline sales_intelligence
stage enrich
  agent data_agent
  -> enrich_company()
  checkpoint after
  on_error retry
stage score
  agent score_agent
  -> score_company()
  checkpoint after
  on_error retry

Practical Applications

• Use case: Safety-critical pipelines use pre/post conditions to block dangerous misclassifications in workflows like mushroom identification. Pitfall: Relying on scattered Python assertions makes it impossible to trace exactly where state drift occurred.
• Use case: B2B sales intelligence systems enforce budget and regional policies before agent execution. Pitfall: Post-hoc logging in tools like LangSmith identifies failures only after resources have already been consumed.

References:

• https://dev.to/deadlyreiter/why-your-llm-agent-needs-contracts-not-just-logs-oo7
• https://github.com/Deadly-Reiter/deed
• https://deed-docs.onrender.com