Cloudflare AI

This demo project is a full-stack application designed to show how to extend traditional web applications for AI agents using the Model Context Protocol (MCP). It integrates three core Cloudflare technologies:

• Static Website: Built with React and Vite, hosted on Worker Assets.
• REST API: Built using Hono and powered by Workers KV.
• MCP Server: Built on top of Workers Durable Objects to provide agentic capabilities.

Identity and authentication are managed via Stytch Consumer.

The ai-search-provider allows you to use Cloudflare AI Search as a managed search service within the Vercel AI SDK. You can upload files to AI Search for indexing and then perform natural language searches or generate chat responses grounded in that retrieved context using the generateText function from the ai package.

import { createAISearchNamespace } from "ai-search-provider";
import { generateText } from "ai";

const aiSearch = createAISearchNamespace({ binding: env.AI_SEARCH });
const docs = aiSearch.get("docs");

const { text } = await generateText({
	model: docs.chat({
		ai_search_options: { retrieval: { max_num_results: 5 } },
	}),
	messages: [{ role: "user", content: "How do I configure caching?" }],
});

The project is organized into a client-server architecture:

• /src/client: Contains the React frontend code.
• /src/server: Contains the Cloudflare Workers backend code.

The stack includes:

• Frontend: React, TypeScript, Vite
• Backend: Cloudflare Workers, Workers AI, Hono, Zod

This demo provides a reference implementation for building an Agent that functions as a Model Context Protocol (MCP) Client. This allows the agent to connect to external services via MCP to discover and execute tools, prompts, and resources.

Key capabilities demonstrated include:

• Connecting an AI agent to a remote MCP server.
• Handling authentication checks using a built-in OAuth flow.
• Discovering and utilizing tools exposed by remote MCP servers.

The Hello World Agent is a minimal implementation demonstrating the core components of a Cloudflare Agent. It includes:

• Agent class: An implementation that extends the base Agent class and provides a simple onRequest handler.
• Request routing: Uses routeAgentRequest to direct incoming requests to the specific Agent instance.
• Durable Object configuration: A minimal setup utilizing SQL storage for state.
• CORS support: Configured to allow cross-origin requests.

The implementation is contained within src/index.ts.

Resumable streaming allows long streaming responses to recover transparently from mid-stream drops (such as transient network blips or edge restarts). When a request is made via the run path (env.AI.run), the AI Gateway returns a cf-aig-run-id header. The resumable-stream engine wraps the response body so that if a mid-stream reader error occurs, it automatically re-attaches to the run using that ID and resumes delivery. To the downstream parser, the stream appears as one continuous connection.

Note: This feature is currently experimental and is being rolled out to the AI Gateway resume backend. It is not yet generally available.

Resumable streaming is only available when using the direct env.AI binding on the run path, as this is the only method that emits the required cf-aig-run-id.

If resume is requested but unavailable, the system performs a no-op and issues a warning rather than failing.

The tool-calling demo follows a request-response flow designed to simulate a client interacting with a weather-capable worker via a local development server:

1. Client: Sends a POST request containing a prompt.
2. Local Dev Server: Receives the request and triggers the worker.
3. Weather Worker: Processes the prompt and determines if a tool call is required.
4. Fetch Weather Data: The worker executes the tool to retrieve external weather information.
5. Response: The data is returned back through the server to the client.

graph TD;
    A[Client] -->|POST Request| B[Local Dev Server]
    B -->|Run Worker| C[Weather Worker]
    C -->|Process Prompt| D[Fetch Weather Data]
    D -->|Return Response| A

The Agent Scheduler implements three primary agentic patterns:

1. Tool Use Pattern: The SchedulerAgent interacts with external AI models to interpret queries and determine the required action type.
2. Planning Pattern: The agent formulates and executes plans based on user queries to align with real-time goals.
3. Autonomous Agent: The SchedulerAgent operates autonomously, managing tasks dynamically and utilizing feedback loops for user interaction.

The project is designed to validate that a local server correctly implements structured output using schema validation. The workflow follows this pattern:

1. Local Dev Server: The application is started locally.
2. Client Request: A client sends a POST request with a prompt to the server.
3. Integration Test: The test suite captures the server's response.
4. Schema Validation: The response is validated against a predefined schema using Zod to ensure structural integrity.
5. Test Outcome: The test passes if the response matches the schema.