From Prompt Craft to the Agent Contract

Enterprises now deploy systems that interpret instructions, retrieve context, select tools, and act on business processes within a partially open space. Governing such systems requires more than model selection and prompt craft. It requires a typed architectural specification that binds intent, capability, policy, decision, source model, control, and evaluation into a single governed unit.

This chapter calls that unit the agent contract. It extends the EA codex specification family established in Chapter 8 into the artifact that closes the gap between architecture and autonomous execution.

What the chapter covers

8 sections, in order.

10.1 When AI stops being a feature and becomes an architectural problem
10.2 Why traditional enterprise architecture fails AI in practice
10.3 From architecture repository to agent contract
10.4 ACME Pharma: a governed clinical protocol assistant
10.5 What this changes for enterprise architects
10.6 Risks, limits, and trade-offs
10.7 Conclusion
10.8 Sources

Figures, tables and listings

5 code listings

Reproduced in full, in the order they appear in the published chapter. The reasoning that connects them is in the book.

apiVersion: ea.codex/v1
kind: AgentContract
metadata:
  id: AGENT-CDRA-001
  name: customer-dispute-resolution-assistant
  status: approved
  version: "1.0.0"
  domain: customer-service
spec:
  intent:
    capability: Customer Service Management
    objective: Reduce time to assemble policy-grounded case summaries
    delegationLevel: L2
    serviceBoundaries:
      allowed:
        - summarize_case_history
        - propose_resolution_options
        - cite_applicable_policy
      forbidden:
        - approve_financial_compensation
        - alter_customer_master_data
        - send_binding_external_commitments
  semanticModel:
    entities:
      - Customer
      - Complaint
      - PolicyClause
      - Product
      - CompensationDecision
    glossaryPack: codex://service/customer-disputes/glossary/v3
    decisionPack: codex://service/customer-disputes/decisions/v5
  sourcePolicy:
    authoritative:
      - crm_case_records
      - approved_service_policy_library
      - product_terms_repository
    conditional:
      - knowledge_base_faq
    prohibited:
      - personal_notes
      - draft_policy_documents
      - public_web_search
  designDecisions:
    retrievalRequired: true
    answerMustInclude:
      - cited_source_ids
    sourcePrecedence:
      - approved_service_policy_library
      - crm_case_records
      - product_terms_repository
      - knowledge_base_faq
    actionProfile: readOnly
    mandatoryEscalationConditions:
      - compensation_above_threshold
      - policy_conflict_detected
      - low_source_confidence
  controls:
    inputGuardrails:
      - redact_payment_card_data
      - reject_requests_for_policy_override
    outputRules:
      - no_legal_commitment_language
      - cite_only_retrieved_sources
      - mark_uncertainty_explicitly
    humanReview:
      requiredBefore:
        - compensation_exception
        - goodwill_offer
    trace:
      storePromptContextHash: true
      storeRetrievedSourceIds: true
      storeDecisionPath: true
  feedback:
    evaluateOn:
      - citation_accuracy
      - policy_alignment
      - escalation_precision
      - average_handling_time_reduction
    reviewCadence: weekly

Figure 10.1: Agent contract for a customer dispute resolution assistant.

apiVersion: ea.codex/v1
kind: AgentInteractionContract
metadata:
  id: AIC-PV-001
  name: triage-to-case-quality-handoff
  status: approved-with-controls
  version: "1.0"
  domain: pharmacovigilance
  owner: pharmacovigilance-ai-governance
spec:
  sourceAgent:
    agentContractRef: AGENT-PV-TRIAGE-001
    role: emitter
    identity:
      verificationMethod: signed-agent-card
      trustAnchor: acme-internal-root-ca
  targetAgent:
    agentContractRef: AGENT-PV-CASE-QUALITY-001
    role: receiver
    identity:
      verificationMethod: signed-agent-card
      trustAnchor: acme-internal-root-ca
  protocol:
    name: A2A
    version: "1.0"
    transport: https
  purpose: >
    Hand off triaged adverse-event candidates to the case quality review
    agent for completeness validation before pharmacovigilance case creation.
  purposeRef: INTENT-PV-001
  capabilityRef: CAP-PV-001
  allowedMessageTypes:
    - TriageOutput
    - QualityAssessment
    - MissingEvidenceRequest
  messageControls:
    - identity-verification
    - data-minimization
    - patient-identifier-redaction
    - purpose-bound-message
  exchange:
    messageDirections:
      TriageOutput: source-to-target
      QualityAssessment: target-to-source
      MissingEvidenceRequest: target-to-source
    dataExchange:
      allowedDataProducts: [DP-PV-TRIAGE-OUTPUT-V1]
      prohibitedFields: [patientFullName, patientNationalId]
      redactionRules:
        - { field: patientReportedNarrative, rule: pii-redaction }
  autonomyBoundary:
    sourceAutonomyLevel: human-supervised
    targetAutonomyLevel: human-supervised
    stopConditions:
      - { condition: maxRoundtrips > 3 }
      - { condition: humanOverride }
  controls:
    - { type: identity-verification, requiredEvidence: signed-agent-card-trace }
    - { type: pii-minimization, requiredEvidence: redaction-log }
  escalation:
    humanRole: pharmacovigilance-case-owner
    triggerConditions: [low-confidence, regulatoryConflict]
    slaMinutes: 30
  termination:
    timeoutSeconds: 1800
    exitConditions: [quality-assessment-completed, escalation-accepted-by-human]
  linkedPrinciples: [AI-005, AI-013, DATA-001, DATA-005]
  linkedDecisions: [DEC-PV-001]
  linkedEvaluations: [EVAL-PV-001]

Figure 10.2: ACME Pharma agent interaction contract.

apiVersion: ea.codex/v1
kind: AgentMemoryPolicy
metadata:
  id: AMP-PV-001
  name: ai-triage-service-memory
  status: approved
  domain: pharmacovigilance
  owner: pharmacovigilance-data-protection-officer
spec:
  agentContractRef: AGENT-PV-TRIAGE-001
  retentionRules:
    - category: session-context
      retention: "1h"
      mode: session
      description: Default in-session ephemeral context
    - category: workflow-state
      retention: "24h"
      mode: workflow-bound
      sensitivityLevel: internal
      reviewFrequency: quarterly
      description: Active triage workflow step and transient context
    - category: user-preference
      retention: "365d"
      mode: persistent
      ownerControl: user
  prohibitedRetention:
    - patient-identifiable-data
  prohibitedCategories:
    - id: patient-identifiable-data
      description: Names, MRN, national IDs, contact details, dates of birth.
      regulatoryAnchor:
        - { framework: HIPAA, obligation: minimum necessary standard }
        - { framework: GDPR, obligation: data minimization (Art 5(1)(c)) }
        - { framework: PMDA, obligation: protection of personal information }
      enforcement: blocking
  auditRequired: true
  controls:
    - { type: memory-deletion-on-request, ownerRole: data-protection-officer,
        slaHours: 72, regulatoryAnchor: GDPR-Art-17 }
    - { type: memory-inspection, ownerRole: data-protection-officer,
        frequency: quarterly, evidenceRequired: inspection-report }
  review:
    ownerRole: data-protection-officer
    frequencyDays: 90

Figure 10.3: ACME Pharma memory policy fragment for the AI Triage Service.

apiVersion: ea.codex/v1
kind: AgentContract
metadata:
  id: AGENT-PROTO-001
  name: protocol-assistant
  status: approved
  version: "1.4.0"
  domain: clinical-study-startup
spec:
  intent:
    capability: Clinical Study Startup Support
    objective: Shorten turnaround for protocol and site-pack question handling
    delegationLevel: L1
    serviceBoundaries:
      allowed:
        - explain approved protocol text
        - compare protocol with country addendum
        - locate relevant SOP references
        - draft non-binding response for study team review
      forbidden:
        - interpret patient-level eligibility decisions
        - provide medical advice
        - modify protocol content
        - submit regulatory responses
  semanticModel:
    entities:
      - Study
      - Protocol
      - ProtocolVersion
      - CountryAddendum
      - SOP
      - InclusionCriterion
      - ExclusionCriterion
      - InvestigatorQuestion
      - EscalationCase
    authoritativeRelations:
      - ProtocolVersion supersedes ProtocolVersion
      - CountryAddendum constrains ProtocolVersion
      - SOP governs Activity
      - InvestigatorQuestion may_trigger EscalationCase
  sourcePolicy:
    authoritative:
      - validated_protocol_repository
      - approved_country_addenda
      - controlled_sop_library
    conditional:
      - lessons_learned_library
    prohibited:
      - email_attachments
      - personal_share_drives
      - draft_medical_commentary
  designDecisions:
    retrievalRequired: true
    retrievalMustBeScopedBy:
      - study_id
      - country_code
      - document_effective_date
    sourcePrecedence:
      - approved_country_addenda
      - validated_protocol_repository
      - controlled_sop_library
      - lessons_learned_library
    answerMustInclude:
      - cited_source_ids
      - document_versions
      - uncertainty_statement_when_applicable
    actionProfile: readOnly
    mandatoryEscalationConditions:
      - conflict_between_sources
      - ambiguity_in_eligibility_language
      - safety_or_adverse_event_reference
      - missing_authoritative_source
  controls:
    outputRules:
      - do_not_state_medical_judgment
      - do_not_invent_missing_document_content
      - distinguish_quote_from_inference
    humanReview:
      requiredBefore:
        - response_sent_to_investigator
        - protocol_deviation_guidance
    trace:
      storeRetrievedDocuments: true
      storeVersionLineage: true
      storeEscalationTrigger: true
  feedback:
    evaluateOn:
      - citation_correctness
      - protocol_alignment
      - escalation_recall
      - response_cycle_time
      - human_override_rate

Figure 10.4: ACME Pharma protocol-assistant agent contract.

package acme.agentrelease
default allow = false
approved_sources := {
  "validated_protocol_repository",
  "approved_country_addenda",
  "controlled_sop_library",
  "lessons_learned_library"
}
deny[msg] if {
  some src
  src := input.agent.source_policy.prohibited[_]
  input.runtime.retrieval_connectors[_] == src
  msg := sprintf("deployment connects to prohibited source: %s", [src])
}
deny[msg] if {
  input.agent.design_decisions.retrieval_required
  count(input.runtime.retrieval_connectors) == 0
  msg := "retrieval is mandatory but no retrieval connector is configured"
}
deny[msg] if {
  not input.runtime.output_controls.citations_required
  msg := "citations are required for this agent"
}
allow if {
  not deny[_]
  input.runtime.mode == "read_only"
  input.runtime.output_controls.citations_required
}

Figure 10.5: Release-time Rego policy enforcing agent-contract conformance (ACP-ARP-012).

The rest of this chapter

The published chapter runs the argument through all 8 sections above. This page reproduces its structure and every exhibit; the analysis is in the book.