Part 1: Cloudflare-Native Reference Architecture for a Full-Stack AI Agent
Publication Scope and IP Boundary: This reference architecture is a personal KrisperTech publication based on public Cloudflare services, publicly available documentation, and a personal demo implementation. It is not an official Cloudflare product document. It does not disclose Cloudflare internal material, customer architecture, roadmap information, proprietary field assets, internal enablement content, source code, private configuration, secrets, or customer-specific implementation patterns. The purpose of this article is to explain a reusable architecture pattern for deploying a secure AI assistant using publicly available Cloudflare developer and security services.
Live demo: https://krisperbot.krispertech.com
The Business Case
Organizations are moving quickly to adopt AI assistants, copilots, and agentic workflows. The reason is straightforward: AI systems can help users find answers faster, summarize complex information, automate repetitive tasks, and interact with knowledge sources using natural language.
But the challenge is not simply building a chatbot.
The real challenge is building an AI assistant that can be operated safely.
A production-grade AI agent needs more than a model. It needs a frontend experience, an agent runtime, persistent session state, controlled tool use, access control, bot protection, observability, logging, rate limiting, and a way to retrieve trusted knowledge.
This reference architecture demonstrates a full-stack pattern for deploying an AI assistant on Cloudflare’s public developer platform. The architecture combines:
A web-based chat interface
Serverless agent runtime
Stateful session handling
LLM inference
AI observability and control
Tool execution through MCP
Browser-based content retrieval
Human verification
Zero Trust access control for protected tool paths
Reusable integration patterns for future knowledge sources
The implementation shown here uses a public KrisperTech website as the knowledge source. However, the pattern is not specific to a blog. The same model can be adapted to internal documentation, APIs, object storage, databases, vector search, ticketing systems, customer portals, or other governed enterprise knowledge sources.
The important idea is this: An AI agent should not be treated as a standalone chatbot. It should be treated as an application architecture with security, observability, and governance designed in from the beginning.
Architecture Overview
This architecture uses Cloudflare as the deployment platform for the major layers of the AI assistant:
Cloudflare Pages hosts the frontend chat interface.
Cloudflare Turnstile verifies that the user is human before inference resources are consumed.
Cloudflare Workers and the Agents SDK provide the AI agent runtime.
Durable Objects provide stateful session handling and conversation persistence.
Workers AI provides model inference.
AI Gateway provides logging, analytics, caching, rate limiting, and policy controls for AI requests.
Cloudflare Access protects the tool execution layer.
MCP provides a structured protocol for exposing tools to the agent.
Browser Run retrieves and renders live web content as grounding material.
KrisperTech.com acts as the initial public knowledge source.
How the Architecture Works
A user visits the AI assistant through a browser. Before the assistant processes the first message, the user completes a Cloudflare Turnstile verification. This helps reduce automated abuse and prevents bots from immediately consuming inference or content retrieval resources.
The frontend is hosted on Cloudflare Pages. It provides the chat interface and streams responses back to the user. The frontend does not hold the core business logic. Its role is to provide the user experience and maintain a live connection to the agent runtime.
The AI agent runs on Cloudflare Workers using the Agents SDK. The agent is responsible for interpreting the user’s question, maintaining the session, deciding whether additional context is required, invoking tools when needed, and returning a response.
When the agent needs to reason over content from KrisperTech.com, it invokes a tool exposed through an MCP server. That MCP server is protected by Cloudflare Access. The agent authenticates using a machine-to-machine service token, while human administrators can authenticate through an identity provider. This allows both human and machine access paths to be governed by a common access control layer.
The MCP tool server uses Browser Run to render the live website, including JavaScript-heavy pages, and extract usable content. That content is returned to the agent as grounding material.
The agent then sends the prompt and context through AI Gateway to Workers AI. AI Gateway provides visibility and control over the AI request path, including logging, analytics, caching, rate limiting, and guardrail capabilities.
Workers AI performs the model inference. The response returns to the agent, and the agent streams the answer back through the frontend to the user.
At a high level, the flow looks like this:
User opens the AI assistant in a browser.
Turnstile verifies the user is human.
The frontend establishes a streaming chat session.
The AI Agent Worker receives the user’s question.
The agent determines whether it needs additional content.
If content is needed, the agent calls the MCP tool server.
Cloudflare Access validates the machine request.
Browser Run retrieves and renders the website content.
The agent sends the grounded prompt through AI Gateway.
Workers AI generates the response.
The agent streams the answer back to the user.
Why This Is a Full-Stack AI Agent Architecture
The term “full-stack” is intentional.
This architecture is not only about calling a model API. It includes the major application layers required to deploy, operate, and govern an AI assistant.
User Experience Layer
The user interacts with a browser-based chat interface. This layer is responsible for usability, session initiation, streaming responses, and presenting answers clearly.
Agent Runtime Layer
The agent runtime handles the core reasoning loop. It receives user input, maintains context, decides when to call tools, invokes model inference, and returns responses.
State Layer
Durable Objects provide session-level state. This allows the system to maintain conversation history and provide a more continuous user experience.
Inference Layer
Workers AI provides the LLM inference layer. The model is not treated as the entire application. It is one component within a larger system.
AI Control Plane
AI Gateway provides observability and policy controls around inference. This is important because AI systems need monitoring, cost visibility, and abuse controls just like any other production service.
Tool Layer
The MCP server exposes capabilities the agent can use. In this implementation, those tools allow the agent to crawl or read KrisperTech.com content.
Access Control Layer
Cloudflare Access protects the tool server. This keeps tool execution from being openly exposed and allows both human and machine access to be governed.
Content Retrieval Layer
Browser Run renders live website content and extracts it for use by the agent. This allows the assistant to reason over current website content rather than relying only on static training data.
Security Layer
Turnstile, Access, service tokens, and AI Gateway controls create multiple checkpoints across the architecture.
Observability Layer
AI Gateway and Access logs provide visibility into AI usage, access events, and operational behaviour.
This is why “full-stack AI agent” is a better description than simply “chatbot.” The architecture covers the end-to-end system, not just the conversational interface.
Component Breakdown
1. Human Verification with Cloudflare Turnstile
Before the assistant processes a user request, Turnstile provides a human verification step.
This matters because AI inference and browser-based content retrieval are not free. A public-facing assistant can be abused by bots, scrapers, automated scanners, or malicious users attempting to generate cost, extract information, or stress the system.
Turnstile acts as a first-line control. It helps ensure that the user interacting with the assistant is more likely to be human before the request reaches the more expensive parts of the stack.
In this architecture, Turnstile is not positioned as the only security control. It is one part of a layered approach that also includes access control, machine authentication, AI request logging, and rate limiting.
Architecture role: Reduce automated abuse before requests reach the AI agent.
2. Frontend on Cloudflare Pages
The frontend is deployed on Cloudflare Pages. It provides the chat user interface and connects the user to the AI agent.
The frontend layer is intentionally lightweight. It does not own the core reasoning logic, model orchestration, tool invocation, or conversation state. Those responsibilities are handled by the agent runtime.
This separation is useful because the frontend can remain simple while the agent layer evolves independently. It also makes the architecture easier to reuse. A future version could replace the web chat interface with another interface, such as a dashboard, internal portal, or voice-driven assistant, while preserving the same backend agent pattern.
Architecture role: Deliver the global web interface and stream AI responses to the user.
3. AI Agent Worker
The AI Agent Worker is the core of the architecture.
It receives user input, manages the conversation flow, decides when tools are needed, and coordinates inference. This is where the assistant becomes more than a static chatbot.
The agent is responsible for several important functions:
Maintaining conversation context
Deciding whether website content is needed
Calling MCP tools when required
Passing grounded prompts to the model
Streaming responses back to the frontend
Handling session-level logic
Enforcing application-level checks before processing requests
The agent runtime is built as serverless compute, which means there is no traditional server to provision, patch, or operate. The architecture can scale with demand while keeping the application model relatively simple.
Architecture role: Coordinate the reasoning loop, session state, tool use, and response streaming.
4. Durable Object Session State
AI assistants are more useful when they can maintain session continuity. Durable Objects provide a stateful execution model that allows each session or agent instance to maintain its own context.
In this architecture, the agent uses persistent session state to retain conversation history and support a more natural user experience.
This matters because agentic systems often require more than a single request-response interaction. A user may ask a question, follow up, clarify, or ask the assistant to compare one answer to another. Session state helps the assistant preserve that context.
Architecture role: Provide stateful, per-session memory for conversation continuity.
5. Workers AI for Model Inference
Workers AI provides the inference layer. In this design, the model is used by the agent to generate responses based on the user’s request and any retrieved grounding material.
The key architectural point is that the model is not the whole system. It is one component in a governed application flow.
The agent controls when inference happens, what context is included, which tools are used, and how the response is returned. This distinction matters because many AI projects fail by treating the model as the architecture. In practice, the model is only one part of a production AI application.
Architecture role: Generate AI responses based on the user request and retrieved context.
6. AI Gateway for Observability and Control
AI Gateway sits in the inference path and provides visibility into AI usage.
This is important because organizations need to understand how AI systems are being used. They need insight into request volume, token usage, latency, costs, errors, caching behavior, and policy enforcement.
AI Gateway can also support controls such as caching, rate limiting, and guardrails. These capabilities help operators manage reliability, spend, and risk without needing to build every control directly into the application.
For a public-facing assistant, this layer is especially important. Without observability, it becomes difficult to understand whether the system is being used normally, abused, or misconfigured.
Architecture role: Provide visibility and control for AI inference traffic.
7. MCP Tool Server
The MCP tool server exposes capabilities that the AI agent can invoke.
In this implementation, the tool server provides two conceptual capabilities:
Crawling the public KrisperTech website
Reading a specific page and returning its content
This allows the agent to retrieve live content when it needs more context to answer a question.
MCP is useful because it separates the agent from the tools it can use. Instead of hardcoding every capability directly into the agent, tools can be exposed through a structured interface. This makes the architecture easier to extend over time.
For example, the same pattern could later expose tools for:
Searching internal documentation
Reading an object from R2
Querying a D1 database
Calling an internal API
Searching a Vectorize index
Looking up support ticket metadata
Retrieving product documentation
The agent does not need to know the full implementation details of each system. It needs a controlled way to discover and invoke approved tools.
Architecture role: Expose approved tools that the agent can use to retrieve information or perform controlled actions.
8. Zero Trust Access for Tool Protection
The MCP tool server should not be left openly accessible.
In this architecture, Cloudflare Access protects the tool layer. The AI agent authenticates to the MCP server using a service token. Human operators can access the same protected application through identity provider authentication.
This is an important security boundary.
The public user interacts with the frontend. The frontend talks to the agent. The agent is the only component that should invoke the protected tools. Access helps enforce that separation.
This does not make the entire architecture a “Zero Trust architecture” by itself. Rather, Zero Trust Access is used as one control within a broader full-stack AI agent architecture.
That distinction matters.
The primary architecture is a full-stack AI agent deployment pattern. Zero Trust is one of the security mechanisms used to protect the tool execution layer.
Architecture role: Protect the MCP tool server and govern human and machine access paths.
9. Browser Run for Live Content Retrieval
The demo uses KrisperTech.com as the knowledge source. Since modern websites often rely on JavaScript rendering, simple HTTP fetching may not return content in a usable format.
Browser Run addresses this by rendering the page in a headless browser and extracting content that can be returned to the agent.
This allows the AI assistant to answer based on live website content rather than relying only on static training data or manually uploaded text.
In this architecture, Browser Run is used for a public website. In an enterprise adaptation, this layer could be replaced or supplemented by other retrieval mechanisms, such as:
R2 for document storage
D1 for structured data
Vectorize for semantic search
APIs for business systems
Internal documentation portals
Knowledge bases
Ticketing systems
CRM systems
Architecture role: Retrieve and render live content that can be used as grounding material for the AI response.
10. Website or Knowledge Source
The knowledge source in this implementation is KrisperTech.com. The assistant can retrieve content from the public site and use that content to answer questions.
However, the website is only an example. The broader pattern is source-agnostic.
The same architecture can be reused with different data sources depending on the organization’s needs. The AI agent does not need to be tied to a website. It needs trusted, governed access to the right information.
That information could live in documents, databases, APIs, object storage, SaaS platforms, or search indexes.
Architecture role: Provide the trusted content the agent uses to ground its responses.
Security Considerations
A public-facing AI assistant introduces several risks that need to be considered from the start. These include:
Bot-driven cost abuse
Prompt injection attempts
Unauthorized tool invocation
Excessive inference usage
Data leakage through logs or prompts
Overly broad access to internal systems
Uncontrolled crawling or retrieval
Lack of auditability
Model hallucination
Sensitive content exposure
This architecture addresses those risks through layered controls.
Turnstile helps reduce automated abuse before the user reaches the agent. Access protects the MCP tool layer. Service tokens provide a machine authentication path for the agent. AI Gateway provides inference observability and policy controls. The MCP layer limits which tools the agent can call.
For a production deployment, additional controls should be considered:
Strict URL allowlisting for browser-based retrieval
Input validation on tool parameters
Output filtering where required
Prompt injection testing
Rate limits by user, IP, or session
Secrets stored outside application code
Service token rotation
Separation between public and private data sources
Logging policies that account for sensitive prompts and responses
Least-privilege permissions for every integration
Human approval flows for sensitive actions
The goal is not to assume that AI agents are safe by default. The goal is to constrain what they can access, observe what they are doing, and design the system so the agent operates within defined boundaries.
Observability Considerations
AI systems need observability for the same reason traditional applications do: operators need to understand what is happening.
For AI applications, observability should include more than uptime. It should include:
Number of AI requests
Token usage
Cost trends
Latency
Error rates
Cache hit rates
Tool invocation patterns
Access events
Denied requests
Abnormal usage
Guardrail activity
AI Gateway provides visibility into the inference path. Cloudflare Access provides visibility into protected application access. Together, these controls help operators understand both the AI side of the system and the access control side of the system.
This matters because AI agents can create new operational blind spots. A user may not just be clicking pages. They may be asking questions, triggering retrieval, invoking tools, and causing inference spend. Without observability, it is difficult to govern that behavior.
Reusable Pattern
Although this demo uses KrisperTech.com as the content source, the architecture is intentionally reusable.
The data source can change while the overall pattern remains the same.
Current Component | Possible Replacement |
Public website content | Internal documentation |
Browser Run | R2 document retrieval |
Browser Run | D1 database query |
Browser Run | Vectorize semantic search |
Browser Run | REST API integration |
Public blog | Knowledge base |
Public content | Authenticated enterprise content |
This makes the architecture useful beyond a single demo.
The reusable pattern is:
Build a frontend for user interaction.
Route requests to a stateful AI agent.
Use a governed inference path.
Expose approved tools through a controlled tool layer.
Protect that tool layer with access control.
Retrieve trusted grounding content.
Observe usage, cost, and access events.
Swap knowledge sources as business needs evolve.
The value of the architecture is not that it answers questions from one website. The value is that it demonstrates a secure and repeatable way to deploy agentic AI systems.
Why This Matters for Enterprise AI
Many organizations are experimenting with AI, but experimentation is not the same as operational readiness.
A prototype can call a model and return a response. A production system needs more.
It needs authentication, authorization, logging, abuse prevention, observability, cost controls, and safe access to tools and data. It also needs clear separation between the user interface, the agent, the model, the tool layer, and the knowledge source.
This architecture demonstrates one way to bring those pieces together.
The broader lesson is that enterprise AI should be designed like an application platform, not like a standalone prompt. The agent needs a secure runtime. The tools need boundaries. The model needs observability. The data sources need governance. The user experience needs to be simple without exposing unnecessary complexity.
This is where secure-by-design architecture becomes important.
As AI assistants become more capable, they will increasingly interact with real systems: documentation, databases, ticketing platforms, customer records, SaaS tools, APIs, and operational workflows. The more capable the agent becomes, the more important the architecture becomes.
The future of AI adoption will not be defined only by which model an organization chooses. It will be defined by how safely and effectively that organization can connect AI systems to knowledge, tools, users, and business processes.
Practical Production Enhancements
This reference architecture is intentionally high level. A production implementation should add controls based on the sensitivity of the use case.
Examples include:
URL and Domain Controls
If an agent can retrieve web content, it should not be allowed to retrieve arbitrary URLs without constraints. Domain allowlisting helps ensure the retrieval layer only accesses approved sources.
Tool Input Validation
Tool parameters should be validated before execution. For example, a read_page tool should check that a requested URL belongs to an approved domain before Browser Run is invoked.
Prompt Injection Testing
If the agent retrieves content from websites, documents, or other user-controlled sources, that content may contain malicious instructions. The system should test how the agent behaves when retrieved content attempts to override system instructions or trigger unauthorized behavior.
Logging and Data Handling Policies
AI logs can contain sensitive user prompts, retrieved context, and model outputs. Operators should decide what is logged, how long it is retained, who can access it, and whether sensitive data should be redacted.
Rate Limits
Public-facing AI systems should have rate limits. These may be applied at the AI Gateway layer, application layer, or both.
Service Token Rotation
Machine credentials should be treated as sensitive secrets. They should be rotated periodically and stored outside the application code.
Human Approval for Sensitive Tools
If future tools perform actions rather than retrieve information, human approval may be required. For example, reading content is lower risk than creating a ticket, sending an email, modifying a record, or initiating a workflow.
Separation of Public and Private Knowledge
Public website content and private enterprise content should not be mixed casually. If the assistant can access internal knowledge, the architecture should include stronger identity, authorization, and data loss prevention controls.
Key Takeaways
A useful AI assistant is more than a model connected to a chat box.
A production-ready AI agent needs a full architecture around it: frontend, runtime, session state, inference, tool use, access control, observability, abuse prevention, and trusted knowledge retrieval.
This reference architecture demonstrates how those layers can be combined using Cloudflare’s public developer and security services.
The most important lessons are:
Treat AI agents as applications, not prompts.
Put controls around tool use.
Use access control for machine-to-machine paths.
Add observability to the inference layer.
Verify users before consuming expensive resources.
Ground responses in trusted content.
Design the knowledge source as a replaceable component.
Keep the architecture reusable across multiple enterprise use cases.
The real question for organizations is not simply, “Can we build an AI assistant?”
The better question is: Can we build an AI assistant that is secure, observable, governed, and reusable?
That is the architecture problem this pattern is designed to address.
Resources
To explore the public Cloudflare services referenced in this architecture, review the relevant Cloudflare documentation for:
Resource | Link |
Cloudflare Agents SDK | |
Workers AI model catalog | |
AI Gateway | |
Browser Run | |
Securing MCP with Zero Trust | |
Turnstile |
Closing Note
This reference architecture began as a personal implementation for KrisperTech, but the pattern is broadly applicable.
AI adoption is moving from experimentation to operational reality. As that shift happens, organizations will need practical patterns for securing agents, governing tool use, observing inference, and connecting AI systems to trusted knowledge sources.
A full-stack AI agent architecture gives teams a way to think beyond the chatbot and toward the complete system required to operate AI safely.
Comments