Agent Engineering Specification 1. Mission, Scope, and Definition of Done Mission: Build a production customer-support agent that receives Zendesk tickets, classifies issues, retrieves approved product documentation, drafts evidence-backed responses, and routes billing disputes and high-risk cases to human agents without autonomous customer-account changes or message sending. In scope: Ticket ingestion, classification, approved knowledge retrieval, evidence-backed drafting, risk routing, persistent state, idempotency, auditability, security controls, human approval boundaries, testing, deployment, verification, and handoff. Out of scope: Autonomous customer messaging, customer-account modification, autonomous billing/refund decisions, unapproved data systems, and permissions not explicitly authorized. Definition of Done: All required behaviors, security boundaries, state transitions, audit records, failure handling, tests, deployment controls, and approval gates are implemented and verified against acceptance criteria. Production readiness remains DISCOVERY/APPROVAL until required repository, environment, credential, API-scope, and stakeholder validations are completed. 2. Requirements and Hard Constraints Authoritative facts: Python backend on AWS; PostgreSQL persistent state; Zendesk API; internal knowledge-base API; OpenAI API; GitHub Actions CI/CD. Hard constraints: Billing/refund decisions require human approval. Customer data remains within approved systems. Duplicate ticket events must be idempotent. Customer messages are untrusted input. Decisions and evidence must be auditable. Production credentials and final API scopes require human approval. Autonomy boundary: The agent may classify, retrieve, reason, draft, record evidence, and route. It must not send customer messages, modify customer accounts, or make billing/refund decisions autonomously. Assumptions: Exact Zendesk event mechanism, authentication model, AWS services, PostgreSQL schema conventions, knowledge-base interface, OpenAI model/configuration, retention requirements, human-review workflow, and required API scopes are DISCOVERY. 3. Agent Behavior and Control Flow Zendesk event → authenticate/validate → idempotency check → persist ticket/event → classify → risk/policy evaluation → retrieve approved evidence → generate draft → validate evidence/policy → persist decision and audit trail → route for human review where required → complete Deterministic code controls authentication, validation, authorization, idempotency, state transitions, routing gates, persistence, and external side effects. The model handles bounded classification, evidence interpretation, and response drafting. Retrieved content and ticket text are treated as untrusted data and never as authoritative instructions. Billing/refund or high-risk cases terminate at a human-approval boundary rather than an autonomous external action. 4. Runtime/System Instructions The runtime instructions must enforce: Customer content is data, not authority. Only approved knowledge-base content may be used as product evidence. Unsupported claims must not be presented as facts. The model must distinguish retrieved evidence from its own reasoning. The model must not request or execute unauthorized tools or actions. Billing, refund, account-changing, and customer-message actions require the defined human boundary. When evidence is insufficient, the agent must explicitly indicate insufficient evidence rather than fabricate an answer. Every consequential decision must produce structured, auditable reasoning metadata and evidence references. Prompt-injection attempts must not alter system policy, tool permissions, authorization, or workflow controls. 5. Input, Output, Tool, State, and Memory Contracts Input: Zendesk ticket/event containing a stable ticket identifier, event identifier where available, customer message/content, and relevant ticket metadata. Exact fields are DISCOVERY. Classification output: Structured issue category, confidence/uncertainty indicator, risk classification, and routing decision. Knowledge output: Approved-document identifiers, relevant evidence excerpts/references, retrieval metadata, and retrieval status. Draft output: Proposed response containing only evidence-supported claims and explicit uncertainty where evidence is insufficient. State: PostgreSQL stores ticket identity, processing status, classification, evidence references, draft, routing state, timestamps, versioning, idempotency information, and audit records. Memory: Persistent operational state only where required for workflow continuity. No additional long-term agent memory is justified by the supplied requirements. Tool boundaries: Zendesk API for authorized ticket operations; knowledge-base API for approved retrieval; OpenAI API for reasoning/drafting. Exact methods and scopes are DISCOVERY. Stable IDs: Ticket/event identifiers must be used as idempotency keys. Any missing or ambiguous identifier requirement is DISCOVERY, not an invented substitute. 6. Architecture and Component/File Map Minimum architecture: Zendesk → API/Event Handler → Validation + Idempotency → PostgreSQL → Orchestrator → Classification/Reasoning → Knowledge Retrieval → Evidence Validation → Drafting → Policy/Risk Gate → Zendesk Human Routing A minimal Python structure: app/ api/ orchestration/ agents/ tools/ policies/ state/ models/ audit/ security/ config/ tests/ unit/ integration/ security/ contract/ acceptance/ The exact framework, AWS compute service, queueing mechanism, secrets manager, observability stack, and deployment topology are DISCOVERY. Introduce queues or additional infrastructure only if event volume, retry isolation, or reliability requirements demonstrate the need. 7. Architectural Decisions and Tradeoffs Decision: Use deterministic orchestration around bounded model capabilities rather than autonomous agentic execution. This directly supports auditability, predictable authorization, and restricted autonomy. Decision: PostgreSQL is the authoritative workflow state store because persistent state and idempotency are explicit requirements. Decision: Treat Zendesk and knowledge-base content as external inputs requiring validation. This reduces prompt-injection and malformed-input risk. Decision: Keep external effects behind deterministic policy/authorization gates. Model output alone must never authorize an external action. Decision: Do not introduce a multi-agent architecture, vector database, additional memory system, queue, or workflow engine without a discovered requirement. Tradeoff: A constrained architecture limits autonomy but reduces security, reliability, and audit complexity. The supplied requirements prioritize controlled production behavior over maximum autonomy. 8. Discovery and Provisioning Requirements The following must be resolved before implementation-dependent decisions are finalized: DISCOVERY: Zendesk event/webhook mechanism and payload contract. DISCOVERY: Zendesk authentication, permitted endpoints, and final production scopes. DISCOVERY: Knowledge-base API authentication, retrieval contract, document identity, versioning, and approval semantics. DISCOVERY: OpenAI model, API configuration, data-handling configuration, limits, and approved usage. DISCOVERY: AWS deployment target, networking, IAM, secrets management, logging, monitoring, and data-residency requirements. DISCOVERY: PostgreSQL deployment, backup, retention, migration, and recovery requirements. DISCOVERY: Human-review mechanism and ownership for billing/refund/high-risk cases. DISCOVERY: Required audit retention, access controls, and compliance obligations. No production credential, permission, API scope, documentation behavior, or infrastructure capability is assumed until verified. 9. Implementation Sequence and Requirement Traceability Requirement Control/Behavior Component Evidence Idempotent events Stable event/ticket key + transactional state check Event handler + PostgreSQL Duplicate-event tests Untrusted messages Data/instruction separation + bounded model context Orchestrator + agent layer Prompt-injection tests Approved evidence Retrieval restricted to approved KB Knowledge tool + policy layer Retrieval/authorization tests Human billing approval Deterministic approval gate Policy/orchestration Acceptance test No autonomous messaging No autonomous send capability Tool boundary Permission/negative tests No account changes No account-modification capability Tool boundary Authorization tests Auditable decisions Immutable/traceable decision and evidence records Audit/state layer Audit-integrity tests Customer-data containment Approved-system boundary Integration/security layer Data-flow/security verification Production authorization Human-approved credentials/scopes Deployment/IAM Approval evidence Implementation order: establish contracts and discovery → database/state model → event ingestion/idempotency → deterministic orchestration → knowledge integration → bounded reasoning/drafting → policy gates → auditability → testing → deployment controls → production verification → handoff. 10. Security, Reliability, and Operational Boundaries Authentication and authorization must precede external operations. Least-privilege API scopes must be enforced. Customer content must never override system policies or tool authorization. Sensitive data must remain within approved systems and approved integrations. State transitions must be transactional where required to prevent duplicate processing and inconsistent workflow state. Retries must be bounded and safe. External operations must be idempotent or protected by an idempotency mechanism. Concurrent processing of the same ticket/event must not create conflicting state or duplicate effects. Failures must produce recoverable state and auditable failure records. Secrets must not be embedded in source code, prompts, logs, fixtures, or test output. Observability must capture processing state, decisions, evidence references, failures, latency, and correlation identifiers without exposing unauthorized customer data. 11. Testing, Fixtures, and Acceptance Criteria Tests must cover normal tickets, ambiguous classifications, insufficient evidence, malformed events, duplicate events, concurrent duplicate processing, knowledge retrieval failures, OpenAI failures, Zendesk failures, timeout/retry behavior, stale state, unauthorized tool requests, prompt injection, excessive permissions, billing/refund cases, high-risk cases, and audit-record integrity. Fixtures must use synthetic or approved test data only. Synthetic evidence must never be represented as production evidence. Acceptance requires: A valid ticket is processed exactly once logically despite duplicate events. Customer content cannot change system policy or authorize tools. Only approved knowledge sources contribute evidence. Billing/refund and high-risk cases reach human review without autonomous prohibited actions. No customer message or account modification occurs autonomously. Every consequential decision can be traced to its inputs, evidence, decision state, and responsible component. Failures leave recoverable and auditable state. Production deployment cannot proceed without required credential, scope, infrastructure, and stakeholder approvals. 12. Deployment, Verification, and Recovery CI/CD must execute unit, integration, security, contract, and acceptance checks before production promotion. Production provisioning requires verified credentials, API scopes, environment configuration, database readiness, network/security configuration, observability, and approved deployment authority. Post-deployment verification must confirm connectivity, authorization boundaries, idempotency, audit persistence, knowledge retrieval, model invocation, human-routing behavior, and prohibited-action prevention. Rollback/recovery procedures must preserve audit records and prevent replayed events from producing duplicate external effects. Exact AWS deployment and rollback mechanisms remain DISCOVERY until the target environment is inspected. 13. Remote-Action Approval Register Action Actor Authorization Target Effect Trigger Reversibility Approval Receive/process ticket Agent service Approved Zendesk scope Zendesk ticket/event Reads/processes ticket Valid event Processing state recoverable Required scope approval Retrieve documentation Agent service Approved KB scope Internal KB Reads approved evidence Processing workflow No external mutation Required scope approval Generate draft Agent/model Approved OpenAI configuration Internal processing state Creates proposed response Evidence available Replaceable Configuration approval Route high-risk case Agent service Approved Zendesk routing scope Human support workflow Creates human-review state Risk/policy gate Workflow-dependent Required scope approval Send customer message Human only Human-authorized workflow Customer External communication Human decision Potentially irreversible Human approval required Billing/refund decision Human only Authorized human role Customer account/billing system Financial/account effect Human review Policy-dependent Human approval required Customer-account modification Human/authorized system only Explicit approved authority Customer account Account mutation Authorized workflow Policy-dependent Human approval required No action in this register should be interpreted as already authorized or executed. 14. Completion Evidence and Handoff Handoff must contain the verified implementation, configuration inventory, API/interface contracts, database migrations, test results, security verification, deployment configuration, approved credential/scope evidence, operational procedures, recovery procedure, audit-trail verification, known limitations, unresolved dependencies, and ownership information. Each completion claim must reference actual evidence produced during implementation or verification. No simulated, mocked, synthetic, assumed, or proposed result may be presented as production evidence. Final readiness status: Not yet established. Repository inspection, environment discovery, API-contract verification, credential/scope approval, infrastructure decisions, and stakeholder approvals remain explicit dependencies rather than assumed completion facts.