Architecture note

Self-hosted AI agent architecture without the mystery layer

A production agent is a system of trust boundaries, execution, tools, data, observation, and human control—not only a model.

Start with trust boundaries

The first architecture question is not which model to use. It is which component may receive messages, hold credentials, read files, call tools, retain memory, and approve high-impact actions.

A five-layer model

  1. Channels: messaging, email, web, voice, CRM, and scheduled triggers.
  2. Host control plane: identity, routing, secrets, policy, sessions, memory, and lifecycle.
  3. Execution environment: the model or agent runtime operating inside a bounded workspace.
  4. Tools and data: APIs, MCP servers, databases, files, and business platforms.
  5. Delivery and observation: output validation, logs, retries, approvals, and monitoring.

Container isolation is not the whole security model

Containers help separate files and processes, but they do not automatically prevent unsafe network access, secret leakage, prompt injection, excessive permissions, or vulnerable dependencies. Production design still needs explicit mounts, network policy, secret handling, tool allowlists, updates, and review.

Memory needs governance

Long-term memory can preserve preferences, prior decisions, and workflow context. It can also preserve inaccurate or sensitive information. Retention rules, user boundaries, deletion paths, and reviewable summaries belong in the design.

Operational readiness

A self-hosted agent should have health checks, restart policies, backups, versioned configuration, audit records, cost visibility, and a human escalation route. If those parts are missing, the system is still a prototype regardless of model quality.

Start with the workflow

Turn the manual work into a system.

Describe what happens today, where it slows down, and what a successful result should look like.