Getting Started

Build your first AI agent using the TypeScript Agent Framework.

Learn how to create a production-ready conversational AI agent with session management and streaming responses by following the typescript-agent-template. This guide walks through the complete implementation from the typescript-agent-template, showing you how to create a production-ready conversational AI agent with session management and streaming responses.

What You'll Build

By the end of this guide, you'll have a fully functional AI agent that:

  • 🧠 Converses intelligently using Anthropic's Claude
  • 💬 Maintains conversation context across multiple interactions
  • 🔄 Streams responses in real-time for better UX
  • 🚀 Scales automatically on Cloudflare's edge network
  • 🛠️ Supports MCP tools for extended capabilities

Prerequisites

Before starting, ensure you have:

  • Node.js 22+ and pnpm installed
  • Cloudflare account with Workers enabled
  • Anthropic API key for Claude integration

Quick Setup

1. Clone and Install

bash

2. Configure local Environment

bash

3. Start Development

bash

4. Test Your Agent

bash

Architecture Overview

The agent uses Cloudflare Durable Objects for session management, ensuring:

  • Persistent Memory: Conversations maintain context across interactions
  • Global Distribution: Sessions accessible from any Cloudflare edge location
  • Auto Scaling: Each session runs independently

Code Breakdown

Let's dive into the complete implementation from src/index.ts:

Core Imports and Setup

typescript

Key Components:

  • Hono: Fast, lightweight web framework for Cloudflare Workers
  • CORS: Cross-origin resource sharing for web applications
  • SimplePromptAgent: Base agent class from our SDK
  • Anthropic: AI provider integration
  • Types: TypeScript definitions for message handling

Main Application Setup

typescript

This creates the main application with CORS enabled for the /agent/* routes, allowing web applications to communicate with your agent.

The SimplePromptAgent Class

typescript

Key Features:

  • Extends SimplePromptAgent: Inherits session management and streaming capabilities
  • Durable Object State: Persistent storage for conversation history
  • Environment Access: Cloudflare Workers environment variables
  • Model Integration: AI provider (Anthropic Claude) connection

Message Processing Logic

typescript

Process Breakdown:

  1. Session ID: Unique identifier for conversation continuity
  2. Messages: Array of conversation messages (user + assistant)
  3. System Prompt: Defines the agent's personality and behavior
  4. Max Steps: Limits reasoning steps for cost control
  5. Streaming: Returns real-time response stream

Chat Endpoint Handler

typescript

Endpoint Logic:

  1. Session Management: Creates new session ID if none provided
  2. Request Parsing: Extracts JSON message payload
  3. Durable Object Lookup: Gets or creates session-specific agent instance
  4. Message Processing: Forwards request to agent for handling

Durable Object Export

typescript

This exports the agent class and the main fetch handler for Cloudflare Workers.

Usage Examples

Basic Chat Interaction

Start a new conversation:

bash

Continue existing conversation:

bash

JavaScript Client Implementation

typescript

React Hook Integration

typescript

Customization Options

1. Modify Agent Personality

typescript

2. Add MCP Tools

typescript

3. Environment Configuration

Update your wrangler.jsonc:

json

Deployment

Deploy to Production

bash

Environment Variables

Set these as Cloudflare Workers secrets:

bash

Next Steps

Now that you have a working agent, explore these advanced features:

  1. Sessions: Deep dive into session handling and state management
  2. AI SDK Integration: Advanced AI provider configurations and tool calling
  3. MCP Tools: Add external capabilities to your agents
  4. Middleware: Custom request/response processing

Troubleshooting

Common Issues

Agent not responding:

  • Check your Anthropic API key is set correctly
  • Verify the wrangler.jsonc configuration
  • Review Cloudflare Workers logs with npx wrangler tail

CORS errors:

  • Ensure CORS is enabled for your routes
  • Check your client's origin is allowed

Session state lost:

  • Verify Durable Objects are properly configured
  • Check session ID consistency in your client

Getting Help

  • Documentation: Comprehensive guides and API references
  • GitHub Issues: Report bugs and request features
  • Discord Community: Real-time support and discussions

You've successfully built your first AI agent! The Simple Prompt Agent demonstrates the core concepts of the TypeScript Agent Framework while providing a solid foundation for more complex implementations.