Enterprise Agent Platform Foundation — Engineering Guide

InfinitySDLC Engineering Guides · 01/12

Reference implementation guide, not a report of a completed client deployment. Code, configurations, metrics and policies are illustrative. Adapt and validate them before production use.

The first agent you build should be the platform around the agents. This article defines a provider-neutral runtime that lets specialized agents use Claude Code, Codex and locally hosted models without duplicating security, retrieval, identity and telemetry logic.

The meaningful design question is not simply which model to call. It is whether changing a model, delegating work or losing an acknowledgement can change who is allowed to act. This guide treats those boundaries as platform responsibilities, not prompt-writing problems.

1.1 Target architecture

Separate the system into five planes. The control plane owns policy, task admission, model routing and human approvals. The model plane contains hosted and self-hosted inference endpoints. The tool plane exposes company systems through curated MCP servers. The knowledge plane provides retrieval and structured context. The execution plane runs code or commands inside bounded sandboxes. This separation prevents an individual agent prompt from becoming the de facto security model.

User / Trigger
      |
      v
[Task API + Policy Engine] -----> [Human Approval Queue]
      |
      +----> [Model Router] ---> Claude / Codex / Local vLLM
      |
      +----> [Retrieval Service] ---> pgvector/Qdrant/OpenSearch + ACL filter
      |
      +----> [MCP Gateway] ---> Git, Jira, CI, K8s, SIEM, Observability, ITSM
      |
      +----> [Sandbox Executor] ---> ephemeral container / microVM
      |
      `----> [OTel + Audit Store + Eval Store]

1.2 Runtime modes: interactive, embedded and sovereign

Do not build twelve different security stacks. Every runtime must receive the same normalized task envelope: actor identity, purpose, data classification, allowed repositories/services, allowed tool verbs, maximum execution time, maximum spend, and required approval level.

task_id: 2ff3...
actor: oidc:user:alice@example.com
purpose: "validate release candidate 2026.09.14"
data_classification: confidential
allowed_resources:
  repos: ["payments-api"]
  environments: ["qa"]
allowed_capabilities:
  - git.read
  - ci.read
  - ci.run_test
  - k8s.read
requires_approval:
  - git.merge
  - k8s.write
limits:
  wall_clock_minutes: 30
  model_budget_usd: 6.00

1.3 Build the MCP gateway as a policy enforcement point

MCP gives you a standard tool interface, but a raw MCP connection should not receive unrestricted downstream credentials. Put a gateway in front of internal servers. The gateway validates workload identity, maps enterprise roles to tool scopes, applies rate limits, strips secrets from outputs, records the invocation and can require an approval token for write operations.

• Tool design: Prefer domain-level tools such as release.get_candidate_context over dozens of low-level REST wrappers. Fewer, distinct tools reduce selection errors and context overhead.
• Read/write split: Expose get_* and propose_* broadly; expose commit_*, merge_*, deploy_* only through explicit policies and approvals.
• Idempotency: Every mutating tool accepts an idempotency key and dry_run=true by default.
• Deterministic outputs: Return typed JSON with stable field names, bounded arrays and explicit truncation metadata.
• Remote-server trust: Pin or continuously attest remote MCP implementations. Treat tool output as untrusted content because prompt injection can arrive through legitimate connectors.

# Tool contract pattern (conceptual)
name: release.propose_deployment
input:
  service: string
  version: string
  environment: enum[qa, staging, production]
  dry_run: boolean = true
output:
  change_id: string
  diff_summary: string
  policy_findings: array
  requires_approval: boolean
side_effects: none_when_dry_run
classification: high_impact

1.4 RAG that is safe enough for agents

Classic chatbot RAG is insufficient because an agent can act on retrieved text. Index source identity and permissions with every chunk, and filter before semantic ranking. Retrieval should produce compact evidence packages, not dump whole documents into context. For code, index both lexical text and symbols: repository, commit SHA, file path, language, symbol, imports/calls and owning team. For operational data, favor time-bounded structured queries over embedding logs blindly.

1. Normalize sources into immutable versions. Keep source_uri, source_version/commit, classification, owner and ACL principal set.
2. Chunk by semantic boundary: code symbol/AST node, document heading, ticket thread, runbook step, ADR section.
3. Compute dense embeddings and lexical terms. Use hybrid retrieval (BM25 + vector), then rerank the top 20-50 candidates.
4. Apply ACL filters before the model sees content. Never rely on the model to ignore unauthorized passages.
5. Attach provenance and retrieval confidence. Require agents to cite source IDs for consequential conclusions.
6. For dynamic systems such as CI, Kubernetes and SIEM, call tools live rather than relying on stale vector snapshots.

def retrieve(query, actor, filters):
    permitted = acl_index.allowed_doc_ids(actor)
    dense = vector.search(query, filter={"id": {"$in": permitted}, **filters}, k=40)
    lexical = bm25.search(query, allowed_ids=permitted, k=40)
    fused = reciprocal_rank_fusion(dense, lexical)
    return reranker.rank(query, fused[:60])[:12]

1.5 Local model serving pattern

Expose self-hosted models through an OpenAI-compatible internal inference endpoint where practical, so agents can switch providers without rewriting every call. For data-center deployment, vLLM is a common high-throughput serving layer; for workstation and edge use, Ollama or llama.cpp can reduce operational overhead. In 2026, practical open-weight choices include OpenAI gpt-oss-20b/120b, Mistral Small 4, Devstral Small 2 for coding, and Qwen3-Coder-class models. Benchmark on your tasks; do not route purely from public benchmark scores.

models:
  local-code:
    endpoint: https://llm.internal/v1
    model: devstral-small-2
    max_data_class: restricted
    preferred_tasks: [code_review, test_generation, refactor]
  local-reasoning:
    endpoint: https://llm.internal/v1
    model: gpt-oss-120b
    max_data_class: restricted
    preferred_tasks: [analysis, structured_decision, batch_triage]

1.6 Evals are part of deployment, not a pre-launch checklist

Create a golden-task suite for each agent containing normal cases, ambiguity, stale data, permission boundaries, prompt-injection payloads, tool failures and rollback scenarios. Grade task success, tool correctness, policy compliance, evidence quality, latency and cost. Run the suite on every prompt, tool schema, retrieval or model change. Agent regressions are frequently caused by harness changes rather than model changes, so version the full stack.

1.7 Production checklist

• Version prompts, skills, MCP schemas, model policy and retrieval configuration together.
• Use ephemeral credentials and sandboxed execution; never place production secrets in RAG.
• Export model/tool/approval events to the SIEM and observability platform.
• Canary new agent versions by team, repository and tool scope.
• Implement a global kill switch that disables mutating tools while preserving read-only diagnosis.
• Keep deterministic automation deterministic. Use the agent to plan, explain and choose; use tested services to execute.

1.8 Design invariants: what a model must never be able to change

Production design extension. Sections 1.8–1.13 develop the handbook’s reference architecture into explicit engineering decisions and acceptance criteria. The scenarios are illustrative, not claims about a completed deployment.

A component diagram describes where capabilities live. A production design must also specify what remains true when an agent delegates work, a provider changes, or a request is retried. In this reference design, the following invariants are enforced outside the model.

Keep authentication, authorization and approval distinct: who is calling, what that identity may do now, and which specific action a qualified human has accepted. A gateway must not treat a successful login as permission to call every downstream service. The MCP security guidance explicitly rejects token passthrough; audience validation and properly separated downstream credentials remain necessary even when all tools share one gateway.

1.9 Follow one task across the five planes

Illustrative task: validate a payments release candidate and prepare a production deployment proposal. Validation and deployment are separate permissions, not two stages of an unrestricted conversation.

1. Admit the task. Resolve the actor, repository, commit and environment from authenticated context. Persist the scope and budget. A phrase such as “urgent production fix” cannot upgrade a QA-only identity.
2. Assemble evidence. Retrieve the applicable payment requirements and current architecture decisions with source versions and access checks. Read CI and environment state live; do not infer readiness from an old indexed test report.
3. Select the execution route. Admit only model endpoints eligible for the data class. Run repository inspection and tests in a task-scoped workspace with synthetic or approved masked fixtures.
4. Verify the result. Collect test results, artifact digests and unresolved blockers. “All tests pass” in generated prose is not enough: the required CI jobs must exist for the exact candidate.
5. Propose, then authorize. Produce a deployment proposal containing the exact artifact, target, rollout policy and preconditions. Obtain an attributable approval; the executor rechecks authorization and current state before applying it.
6. Close with evidence. Record what actually changed and whether independent health checks passed. A rejected proposal, a successful validation and an executed deployment are three different outcomes.

The platform’s output is therefore a verifiable chain from request to result, not merely a polished answer. The QA guide and Release Orchestration guide define the specialist contracts used in this example.

1.10 Failure semantics: a timeout is not a rollback

The hardest write failure is ambiguous completion: the downstream service performs the action, but the caller never receives the acknowledgement. Temporal’s Activity documentation describes this retry hazard and the need for idempotency at the service boundary. A durable workflow does not, by itself, make an arbitrary external side effect exactly-once.

Persist a stable operation ID before dispatch. Bind its idempotency key to a canonical intent including tenant, target, action and parameters; the same key with different parameters must be rejected. The downstream system must support atomic deduplication, a transactional boundary or reliable reconciliation. A check-then-write record in the agent’s own database cannot eliminate the crash window between two independent systems.

Represent these distinctions in persisted state: AWAITING_APPROVAL, DISPATCHED, OUTCOME_UNKNOWN, VERIFIED and FAILED should not collapse into a single “done” flag. Store operation IDs and compact evidence references separately from conversational memory. Compensation is a new controlled action, not an assumed consequence of cancellation.

1.11 Isolation must extend beyond the vector database

Tenant isolation is incomplete when retrieval is filtered correctly but cached answers, traces or generated artifacts cross the same boundary. Define the tenant and authorization context at admission, then propagate it to retrieval, cache lookup, object storage, queues, tool execution and audit access. Derive these values from authenticated state, not model-generated arguments.

For reusable context, include tenant, authorization context, source versions and policy revision in the cache identity; reauthorize before returning a hit. Permission revocation also needs an explicit freshness contract. For sensitive sources, recheck access before use and invalidate affected evidence packages. If current permissions cannot be established, withhold the material rather than treating an old successful lookup as permanent authorization. Restart or rebuild an affected model session when previously supplied context can no longer be used.

Read-only does not mean harmless. A read-only connector can expose confidential documents to an ineligible model or logging backend. Apply data-class rules to embeddings, reranking, prompt traces, debugging exports and backups as well as the primary model request. A local inference endpoint is only one part of that data path.

Use telemetry to record task IDs, policy decisions, timings, tool names and evidence references; do not log complete prompts and tool payloads by default. OpenTelemetry’s sensitive-data guidance emphasizes minimization and implementer responsibility. Detailed diagnostic capture should be scoped, access-controlled and retention-limited; redaction should happen before export, not only in the monitoring UI.

1.12 What to build, what to reuse, and when not to build a mesh

The five planes are responsibility boundaries, not a requirement for five independently deployed microservices. Start with the smallest system that can enforce and test those boundaries. If a workflow is a predictable sequence of API calls, keep it deterministic. Add an agent where interpretation or adaptive investigation is valuable; add specialist agents where distinct tools, permissions or evaluation criteria justify them.

Provider-neutral does not mean every provider is interchangeable. OpenAI’s App Server design exposes richer session and event semantics than a simple model endpoint. Preserve those capabilities through adapters and explicit capability negotiation; do not pretend an OpenAI-compatible inference API reproduces an entire coding harness.

A shared control plane also concentrates privilege and failure risk. Centralize policy ownership, not necessarily every data transfer. Regional or tenant-isolated execution cells can enforce versioned policy near protected resources. Define bounded policy leases, revocation behavior and admission limits; do not let a disconnected cell continue privileged writes indefinitely under stale policy. Keep interactive and batch queues separate when their latency needs differ.

1.13 A production acceptance contract, not a maturity score

Validate the boundaries with reproducible tests. The following is a proposed acceptance suite, not a claim that a deployment has already passed it.

Anthropic’s evaluation guidance distinguishes an agent’s transcript from the resulting state of the environment and combines code-based, model-based and human grading. Apply that distinction here: boundary violations are separate release blockers, not errors that a high average task score can hide. Report success by task class, data class and allowed autonomy, with sample sizes and repeated trials where relevant. The earlier percentage targets are illustrative, not universal production thresholds.

For economics, measure the cost of a verified outcome rather than a successful-looking model response. For a fixed cohort and observation window, include unsuccessful attempts, retries, tool compute, allocated inference capacity and human review in the numerator; count only independently verified outcomes in the denominator.

cost_per_verified_outcome =
    (inference + tool_compute + allocated_platform_cost
     + human_review + recovery_and_retry_cost)
    / independently_verified_outcomes

Report the result as undefined when there are no verified outcomes. Track queue time, active execution time and approval wait separately, so infrastructure tuning is not confused with human decision latency. The production review should end with concrete artifacts: an authorization matrix, a tested operation contract, a failure-replay report, a versioned routing policy and a named operational owner. Those artifacts demonstrate readiness more convincingly than the number of agents on a diagram.

Implementation Blueprint: Build the Shared Runtime

Implementation sequence

1. Build a task-admission API that persists actor identity, purpose, data classification, resource scope, requested capability class, deadline and budgets before the first model call.
2. Run policy admission (OPA/Cedar or equivalent). The response must specify allowed model classes, MCP tools, network profile, maximum agency and required approvals.
3. Deploy a curated MCP gateway. Register every server/tool with owner, version, risk class and auth mode. Do not let production agents discover arbitrary public MCP servers.
4. Deploy an ACL-aware retrieval service independently from the agent. It owns hybrid search, reranking, source provenance and evidence packaging.
5. Deploy a sandbox executor for shell/code operations. Each task gets an ephemeral filesystem, bounded CPU/RAM, egress allowlist, short-lived credentials and a hard timeout.
6. Implement provider adapters for Claude/Claude Code, Codex App Server/SDK and OpenAI-compatible local inference. Normalize tool calls, cancellation, structured outputs and usage telemetry.
7. Export task, model, retrieval, tool, approval and policy events to OpenTelemetry plus an immutable audit store.
8. Create a regression pipeline that replays golden tasks whenever any prompt, skill, MCP schema, model, quantization, retrieval parameter or runtime changes.

Core schema

tasks(task_id, actor_id, purpose, data_class, status, policy_version, created_at)
agent_runs(run_id, task_id, agent_type, model_id, prompt_version, started_at, ended_at)
tool_calls(call_id, run_id, server_id, tool_name, args_hash, approval_id, status, latency_ms)
retrieval_evidence(evidence_id, run_id, source_uri, source_version, acl_hash, score)
approvals(approval_id, task_id, action_hash, approver_id, decision, decided_at)
eval_results(eval_id, artifact_version, suite, score, violations, created_at)

Provider adapter contract

class AgentProvider:
    async def start(task, policy, tools, context) -> Session: ...
    async def continue_(session, tool_results) -> AgentTurn: ...
    async def cancel(session) -> None: ...
# AgentTurn = text + structured_output + tool_calls + stop_reason + provider_metadata

The key design rule is that model-specific settings never become the enterprise authorization system. CLI or SDK permissions can add restrictions, but resource and action authorization must come from the control plane and downstream services.

Shared Platform Assumptions

• Execution plane: Kubernetes or equivalent isolated compute; ephemeral sandboxes for high-agency tools; separate non-production and production credentials.
• Identity: OIDC/SAML for humans; workload identity for agents; short-lived scoped tokens; no shared static API keys in prompts or vector stores.
• Tool plane: Internal MCP gateway exposes curated tools. Prefer read-only tools by default; writes are split into proposal and commit operations.
• Knowledge plane: Hybrid retrieval with ACL filtering, code-aware chunking, metadata filters, reranking and source provenance.
• Model plane: Claude/Codex for frontier reasoning and coding, open-weight models for sovereign/local workloads; centralized routing and evaluation.
• Telemetry: OpenTelemetry traces/logs/metrics plus agent-native events: prompt class, tool call, approval, retrieval sources, model choice, token/latency, outcome and evaluator score.
• Governance: Policy-as-code, human approvals for irreversible operations, immutable audit logs, golden-task evals and staged rollouts.

Terminology and implementation assumptions from the source handbook

The following paragraph preserves the source handbook’s version assumptions; it is not a certification that those versions or defaults apply to a particular deployment. The new production design notes use explicit capability and policy contracts rather than depending on those version labels.

MCP references in this handbook assume the 2026-07-28 protocol generation, whose core moved toward stateless request/response operation, cacheable capability lists and stronger enterprise authorization patterns. For OpenAI Codex, embedded products should prefer the Codex App Server when they need rich session semantics; MCP-server mode is useful when Codex itself should be invoked as a tool in an MCP-oriented architecture. For Claude Code, use sandboxing/permission controls, Agent Skills for reusable procedural knowledge and explicitly vetted MCP servers. Avoid disabling permissions globally in production automation.

Appendix A. Minimal implementation backlog

Appendix B. Standard MCP tool review checklist

• Does the tool have one clear purpose and a non-overlapping name?
• Are inputs strongly typed, bounded and described in business/domain language?
• Is the output concise, structured and explicit about truncation?
• Is read-only the default? For writes, is dry-run available?
• Are side effects documented and idempotent?
• Can access be scoped by actor/resource/action?
• Does the server avoid returning secrets and unnecessary PII?
• Is output treated as untrusted content and provenance attached?
• Are timeouts, pagination, retries and rate limits defined?
• Are tool calls logged with task ID, actor, arguments hash, result status and approval reference?
• Can the tool be disabled centrally without redeploying every agent?
• Is there an eval task that proves the agent can select and use the tool correctly?

Appendix C. Recommended repository layout

agent-platform/
  control-plane/
    task-api/
    policy/
    approvals/
    model-router/
  mcp/
    scm/
    work-management/
    ci/
    kubernetes/
    observability/
    security/
  retrieval/
    ingest/
    acl/
    hybrid-search/
    reranker/
  agents/
    discovery/
    architecture/
    environment/
    qa/
    release/
    observability/
    security-prevention/
    threat-detection/
    reliability/
    incident-response/
  evals/
    golden-tasks/
    adversarial/
    incident-replays/
  deploy/
    helm/
    terraform/

Final Engineering Checklist

• One shared control plane governs all twelve agents.
• No production write tool is authorized by prompt text alone.
• MCP servers are curated, versioned, authenticated and observable.
• RAG enforces ACLs before ranking and preserves provenance.
• Dynamic operational state is queried live rather than treated as stale embeddings.
• Claude Code/Codex run in bounded workspaces with explicit network and credential policies.
• Local models are production artifacts with pinned runtime/template/quantization versions.
• Every agent has golden tasks, adversarial tasks and failure-recovery tests.
• Every high-impact action is attributable, reversible where possible, and has deterministic verification.
• A kill switch can disable mutation globally without disabling read-only diagnosis.

Source Handbook and Further Reading

This series is adapted from Building an Enterprise AI Agent Mesh: 12 Engineering Guides for Claude Code, OpenAI Codex, MCP, RAG, and Self-Hosted Open-Weight Models, September 2026. The links below are the handbook’s further-reading list; model, protocol and tool-version references require validation for the chosen deployment.

• OpenAI — Unrolling the Codex agent loop
• OpenAI — Unlocking the Codex harness: how we built the App Server
• OpenAI — Running Codex safely at OpenAI
• OpenAI — Introducing upgrades to Codex
• OpenAI — gpt-oss open-weight models
• OpenAI — Introducing gpt-oss
• Anthropic — Writing effective tools for agents
• Anthropic — How we contain Claude across products
• Anthropic — Claude Code auto mode
• Anthropic — Claude Code sandboxing
• Anthropic — Equipping agents with Agent Skills
• Anthropic — Effective harnesses for long-running agents
• Anthropic — Demystifying evals for AI agents
• Anthropic — Code execution with MCP
• Model Context Protocol — 2026-07-28 specification release
• Mistral AI — Devstral 2
• Mistral AI — Mistral Small 4
• Qwen — Qwen Code / Qwen3-Coder

Explore the Series

Next guide: Product Discovery Agent

1. Enterprise Agent Platform Foundation
2. Product Discovery Agent
3. Planning & Architecture Agent
4. Environment Agent
5. QA & Validation Agent
6. Change & Release Orchestration Agent
7. Observability Agent
8. Security Prevention Agent
9. Threat Detection Agent
10. Risk & Reliability Agent
11. Incident Response Agent
12. AI Model Router Agent