march-start-cli 0.1.0

package/dist/template/README.md

@@ -0,0 +1,1092 @@
+# Medical Q&A Agent Template (TypeScript)
+
+A complete TypeScript template for building AI agents with the March Agent SDK. This template demonstrates a medical Q&A agent with conversation history, attachment handling, and LLM streaming.
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 18+ and pnpm
+- **March AI Platform running** (from the parent directory: `cd .. && docker-compose up`)
+- OpenAI API key
+
+### Setup
+
+1. Copy environment variables:
+   ```bash
+   cp env.example .env
+   ```
+
+2. Edit `.env` with your values:
+   ```env
+   OPENAI_API_KEY=sk-your-openai-api-key
+   GATEWAY_URL=agent-gateway:8080
+   GATEWAY_API_KEY=your-gateway-api-key
+   ```
+
+3. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+4. Start the agent:
+   ```bash
+   pnpm dev
+   ```
+
+### Local Development
+
+```bash
+# Development with hot reload
+pnpm dev
+
+# Build for production
+pnpm build
+
+# Run production build
+pnpm start
+
+# Type check
+pnpm typecheck
+```
+
+## Project Structure
+
+```
+agent-ts-template/
+├── src/
+│   └── agent.ts              # Main agent implementation
+├── env.example               # Environment variables template
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+---
+
+## March Agent SDK Reference
+
+### App Configuration
+
+Create and configure the March Agent application:
+
+```typescript
+import { config } from 'dotenv'
+import { resolve } from 'path'
+import { MarchAgentApp } from '@march/agent'
+
+// Load environment variables (use override: true to ensure .env takes precedence)
+config({ path: resolve(process.cwd(), '.env'), override: true })
+
+const app = new MarchAgentApp({
+    gatewayUrl: process.env.GATEWAY_URL || 'localhost:8080',
+    apiKey: process.env.GATEWAY_API_KEY || 'your-api-key',
+    heartbeatInterval: parseInt(process.env.HEARTBEAT_INTERVAL || '10'),
+    secure: process.env.CONNECTION_SECURE === 'true',
+})
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `gatewayUrl` | Agent Gateway address (host:port) |
+| `apiKey` | API key for gateway authentication |
+| `heartbeatInterval` | Heartbeat interval in seconds (default: 60) |
+| `secure` | Use TLS for connections (default: false) |
+
+---
+
+### Agent Registration
+
+Register your agent with the platform:
+
+```typescript
+const agent = await app.registerMe({
+    name: 'medical-qa-agent-ts',
+    about: 'A medical Q&A agent that provides health information',
+    document: `
+        Medical Q&A Agent provides accurate, evidence-based information
+        about general medical topics, symptoms, and health questions.
+    `,
+    representationName: 'Medical Assistant (TS)',
+    baseUrl: process.env.AGENT_BASE_URL || 'http://localhost:8060',
+    metadata: {
+        version: '1.0.0',
+        category: 'healthcare',
+        language: 'typescript',
+    },
+})
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `name` | Unique identifier for the agent (used for routing) |
+| `about` | Short description for agent listings |
+| `document` | Detailed documentation about capabilities |
+| `representationName` | Display name in the UI (optional) |
+| `baseUrl` | Base URL for iframe artifacts (optional) |
+| `metadata` | Custom key-value data (optional) |
+
+---
+
+### Message Handling
+
+Handle incoming messages with the `onMessage()` method:
+
+```typescript
+import { Message } from '@march/agent'
+
+agent.onMessage(async (message: Message, sender: string) => {
+    // sender is "user" or the name of another agent
+    console.log(`Message from ${sender}: ${message.content}`)
+
+    const streamer = agent.streamer(message)
+    streamer.stream(`You said: ${message.content}`)
+    await streamer.finish()
+})
+```
+
+#### Filtering by Sender
+
+```typescript
+// Only handle messages from users
+agent.onMessage(async (message, sender) => {
+    // This handler only receives messages where sender === 'user'
+}, { senders: ['user'] })
+
+// Exclude messages from a specific agent
+agent.onMessage(async (message, sender) => {
+    // This handler receives all messages EXCEPT from 'other-agent'
+}, { senders: ['~other-agent'] })
+
+// Handle messages from specific agents
+agent.onMessage(async (message, sender) => {
+    // Only from 'analyzer-agent' or 'summarizer-agent'
+}, { senders: ['analyzer-agent', 'summarizer-agent'] })
+```
+
+#### Message Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `content` | `string` | The message text |
+| `conversationId` | `string` | Unique conversation identifier |
+| `userId` | `string` | User who sent the message |
+| `id` | `string` | Unique message ID |
+| `createdAt` | `string` | ISO timestamp |
+| `metadata` | `Record<string, unknown> \| undefined` | Custom metadata from frontend |
+| `schema` | `Record<string, unknown> \| undefined` | JSON schema for form responses |
+| `attachment` | `AttachmentInfo \| undefined` | File attachment metadata |
+| `conversation` | `Conversation \| undefined` | Helper for conversation history |
+| `memory` | `Memory \| undefined` | Helper for long-term memory |
+
+#### Accessing Frontend Metadata
+
+The frontend can send custom metadata with messages:
+
+```typescript
+agent.onMessage(async (message, sender) => {
+    if (message.metadata) {
+        const source = message.metadata.source as string || 'unknown'
+        const priority = message.metadata.priority as string || 'normal'
+        console.log(`Request from ${source} with priority ${priority}`)
+    }
+})
+```
+
+---
+
+### Streaming Responses
+
+Stream responses using the Streamer:
+
+```typescript
+agent.onMessage(async (message, sender) => {
+    const streamer = agent.streamer(message)
+    streamer.stream('Hello ')
+    streamer.stream('World!')
+    await streamer.finish()
+})
+```
+
+#### With LLM Streaming (LangChain.js)
+
+```typescript
+import { ChatOpenAI } from '@langchain/openai'
+import { HumanMessage, SystemMessage, BaseMessage } from '@langchain/core/messages'
+
+const llm = new ChatOpenAI({
+    model: process.env.OPENAI_MODEL || 'gpt-4o-mini',
+    streaming: true,
+    openAIApiKey: process.env.OPENAI_API_KEY,
+})
+
+agent.onMessage(async (message, sender) => {
+    const messages: BaseMessage[] = [
+        new SystemMessage('You are a helpful assistant.'),
+        new HumanMessage(message.content),
+    ]
+
+    const streamer = agent.streamer(message)
+    const stream = await llm.stream(messages)
+
+    for await (const chunk of stream) {
+        if (chunk.content) {
+            streamer.stream(chunk.content as string)
+        }
+    }
+
+    await streamer.finish()
+})
+```
+
+#### Response Metadata
+
+Attach metadata to your response. This metadata is persisted with the message:
+
+```typescript
+const streamer = agent.streamer(message)
+streamer.setMessageMetadata({
+    model: 'gpt-4o-mini',
+    step: 'diagnosis',
+    confidence: 0.95,
+    tokens_used: 150,
+})
+streamer.stream('Here is my response...')
+await streamer.finish()
+```
+
+#### Event Types and Non-Persisted Content
+
+Use event types to categorize stream content. Use `persist: false` for content that shouldn't be saved to history:
+
+```typescript
+const streamer = agent.streamer(message)
+
+// Thinking indicator (not saved to history)
+streamer.stream('Analyzing your question...', { persist: false, eventType: 'thinking' })
+
+// Main content (saved to history)
+streamer.stream('Here is my response...')
+
+await streamer.finish()
+```
+
+#### Multi-Turn Conversations (Awaiting)
+
+Use `awaiting: true` to ensure the next user response comes back to this agent:
+
+```typescript
+agent.onMessage(async (message, sender) => {
+    const streamer = agent.streamer(message, { awaiting: true })
+    streamer.stream('What symptoms are you experiencing?')
+    await streamer.finish()
+    // The next message from the user will be routed back to this agent
+})
+```
+
+#### Artifacts
+
+Attach files, documents, or iframes to your response:
+
+```typescript
+const streamer = agent.streamer(message)
+
+streamer.addArtifact({
+    url: `/api/reports/lab-results.pdf`,
+    type: 'document',
+    title: 'Lab Results',
+    description: 'Your recent blood work results',
+    metadata: { size: 1024000, mimeType: 'application/pdf' }
+})
+
+streamer.addArtifact({
+    url: `/dashboard/${message.conversationId}`,
+    type: 'iframe',
+    title: 'Patient Dashboard',
+    description: 'Interactive dashboard showing conversation statistics',
+})
+
+streamer.stream('Here are your results.')
+await streamer.finish()
+```
+
+| Artifact Type | Use Case |
+|---------------|----------|
+| `document` | PDFs, reports, guides |
+| `image` | Charts, diagrams, photos |
+| `iframe` | Interactive content, dashboards |
+| `video` | Tutorials, demos |
+| `audio` | Voice messages |
+| `code` | Source code snippets |
+| `link` | External URLs |
+| `file` | Generic downloads |
+
+---
+
+### Response Schema (Forms)
+
+Render forms in the frontend using JSON Schema. The platform validates responses automatically.
+
+#### Requesting Form Input
+
+```typescript
+agent.onMessage(async (message, sender) => {
+    const streamer = agent.streamer(message, { awaiting: true })
+
+    streamer.setResponseSchema({
+        type: 'object',
+        title: 'Symptom Assessment',
+        properties: {
+            symptom: {
+                type: 'string',
+                title: 'Primary Symptom'
+            },
+            duration: {
+                type: 'string',
+                title: 'Duration',
+                enum: ['Less than 24 hours', '1-3 days', 'More than 3 days']
+            },
+            severity: {
+                type: 'integer',
+                title: 'Severity (1-10)',
+                minimum: 1,
+                maximum: 10
+            }
+        },
+        required: ['symptom', 'severity']
+    })
+
+    streamer.stream('Please describe your symptoms:')
+    await streamer.finish()
+})
+```
+
+#### Handling Form Responses
+
+When a user submits a form, `message.schema` contains the schema and `message.content` contains the JSON response:
+
+```typescript
+agent.onMessage(async (message, sender) => {
+    if (message.schema) {
+        // This is a form response - parse the JSON
+        const data = JSON.parse(message.content)
+        const symptom = data.symptom as string
+        const severity = data.severity as number
+
+        const streamer = agent.streamer(message)
+        streamer.stream(`You reported ${symptom} with severity ${severity}/10.`)
+        await streamer.finish()
+    } else {
+        // Regular text message - show the form
+        const streamer = agent.streamer(message, { awaiting: true })
+        streamer.setResponseSchema({ /* ... */ })
+        streamer.stream('Please fill out the symptom form:')
+        await streamer.finish()
+    }
+})
+```
+
+---
+
+### Attachment Handling
+
+Handle file attachments (images, PDFs) uploaded by users.
+
+#### Checking for Attachments
+
+```typescript
+agent.onMessage(async (message, sender) => {
+    if (message.hasAttachment() && message.attachment) {
+        const attachment = message.attachment
+        console.log(`Received: ${attachment.filename}`)
+        console.log(`Type: ${attachment.contentType}`)
+        console.log(`Size: ${attachment.size} bytes`)
+
+        // Check type by contentType
+        if (attachment.contentType?.startsWith('image/')) {
+            console.log('This is an image')
+        } else if (attachment.contentType === 'application/pdf') {
+            console.log('This is a PDF')
+        }
+    }
+})
+```
+
+#### Attachment Metadata
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `url` | `string` | Download URL path |
+| `filename` | `string` | Original filename |
+| `contentType` | `string` | MIME type (e.g., `image/jpeg`, `application/pdf`) |
+| `size` | `number \| undefined` | File size in bytes |
+| `fileType` | `string \| undefined` | Plain text type (e.g., `png`, `pdf`) |
+
+#### Downloading Attachments
+
+Download methods make API calls - use only when you need the content:
+
+```typescript
+agent.onMessage(async (message, sender) => {
+    if (message.hasAttachment()) {
+        // Download as Buffer
+        const content = await message.getAttachmentBytes()
+
+        // Download as base64 (for LLM vision APIs)
+        const base64Data = await message.getAttachmentBase64()
+    }
+})
+```
+
+#### Image Processing with Vision LLM
+
+```typescript
+import { ChatOpenAI } from '@langchain/openai'
+import { HumanMessage } from '@langchain/core/messages'
+
+const visionLlm = new ChatOpenAI({
+    model: 'gpt-4o',
+    streaming: true,
+    openAIApiKey: process.env.OPENAI_API_KEY,
+})
+
+agent.onMessage(async (message, sender) => {
+    if (message.hasAttachment() && message.attachment?.contentType?.startsWith('image/')) {
+        const base64Image = await message.getAttachmentBase64()
+        const contentType = message.attachment.contentType
+
+        const userMessage = new HumanMessage({
+            content: [
+                {
+                    type: 'text',
+                    text: message.content || 'Describe this image',
+                },
+                {
+                    type: 'image_url',
+                    image_url: {
+                        url: `data:${contentType};base64,${base64Image}`,
+                    },
+                },
+            ],
+        })
+
+        const streamer = agent.streamer(message)
+        const stream = await visionLlm.stream([userMessage])
+
+        for await (const chunk of stream) {
+            if (chunk.content) {
+                streamer.stream(chunk.content as string)
+            }
+        }
+
+        await streamer.finish()
+    }
+})
+```
+
+#### PDF Processing
+
+```typescript
+// Note: PDF text extraction requires additional libraries like pdf-parse
+// This example shows how to acknowledge PDF attachments
+
+agent.onMessage(async (message, sender) => {
+    if (message.hasAttachment() && message.attachment?.contentType === 'application/pdf') {
+        const attachment = message.attachment
+        const streamer = agent.streamer(message)
+
+        streamer.stream(`I received your PDF document: ${attachment.filename}`)
+        streamer.stream(`\nFile size: ${Math.round((attachment.size || 0) / 1024)} KB`)
+
+        // To actually process PDF content, you would:
+        // 1. Install pdf-parse: pnpm add pdf-parse
+        // 2. Download the file: const buffer = await message.getAttachmentBytes()
+        // 3. Extract text: const pdfData = await pdfParse(buffer)
+        // 4. Use pdfData.text for LLM processing
+
+        await streamer.finish()
+    }
+})
+```
+
+---
+
+### Conversation History
+
+Access conversation history for context:
+
+```typescript
+agent.onMessage(async (message, sender) => {
+    if (message.conversation) {
+        // Get all messages in this conversation
+        const history = await message.conversation.getHistory({ limit: 10 })
+
+        // Get messages involving current agent (default)
+        const agentHistory = await message.conversation.getAgentHistory({ limit: 10 })
+
+        // Get messages involving a specific agent
+        const otherHistory = await message.conversation.getAgentHistory({
+            agentName: 'other-agent',
+            limit: 10,
+        })
+
+        for (const msg of history) {
+            console.log(`${msg.role}: ${msg.content}`)
+        }
+    }
+})
+```
+
+| Method | Description |
+|--------|-------------|
+| `getHistory({ limit })` | All messages in the conversation |
+| `getAgentHistory({ limit })` | Messages sent to/from current agent |
+| `getAgentHistory({ agentName, limit })` | Messages sent to/from a specific agent |
+
+#### Using History with LLMs
+
+```typescript
+import { HumanMessage, AIMessage, SystemMessage, BaseMessage } from '@langchain/core/messages'
+
+const SYSTEM_PROMPT = 'You are a helpful medical assistant.'
+
+agent.onMessage(async (message, sender) => {
+    const messages: BaseMessage[] = [new SystemMessage(SYSTEM_PROMPT)]
+
+    // Load conversation history
+    if (message.conversation) {
+        const history = await message.conversation.getAgentHistory({ limit: 20 })
+        for (const msg of history) {
+            if (msg.role === 'user') {
+                messages.push(new HumanMessage(msg.content))
+            } else {
+                messages.push(new AIMessage(msg.content))
+            }
+        }
+    }
+
+    // Add current message
+    messages.push(new HumanMessage(message.content))
+
+    // Stream response
+    const streamer = agent.streamer(message)
+    const stream = await llm.stream(messages)
+
+    for await (const chunk of stream) {
+        if (chunk.content) {
+            streamer.stream(chunk.content as string)
+        }
+    }
+
+    await streamer.finish()
+})
+```
+
+---
+
+### AI Memory (Long-term)
+
+Search across all user conversations using semantic search:
+
+```typescript
+agent.onMessage(async (message, sender) => {
+    if (message.memory) {
+        // Search all user's conversations
+        const results = await message.memory.queryAboutUser({
+            query: message.content,
+            limit: 5,
+            threshold: 70,
+        })
+
+        for (const result of results) {
+            console.log(`Score: ${result.similarity}`)
+            console.log(`Content: ${result.content}`)
+        }
+
+        // Search only current conversation
+        const convResults = await message.memory.queryAboutConversation({
+            query: 'previous symptoms',
+            limit: 3,
+        })
+
+        // Get user summary
+        const summary = await message.memory.getUserSummary()
+        if (summary) {
+            console.log(`User summary: ${summary.summary}`)
+        }
+    }
+})
+```
+
+| Method | Description |
+|--------|-------------|
+| `queryAboutUser({ query, limit, threshold })` | Search all user conversations |
+| `queryAboutConversation({ query, limit, threshold })` | Search current conversation |
+| `getUserSummary()` | Get aggregated user summary |
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `query` | required | Semantic search query |
+| `limit` | 10 | Maximum results (1-100) |
+| `threshold` | 70 | Minimum similarity score (0-100) |
+
+---
+
+### Extensions
+
+#### LangGraph Integration
+
+Use `HTTPCheckpointSaver` to persist LangGraph state:
+
+```typescript
+import { MarchAgentApp, Message } from '@march/agent'
+import { HTTPCheckpointSaver } from '@march/agent/extensions/langgraph'
+import { StateGraph, START, END, Annotation } from '@langchain/langgraph'
+import { ChatOpenAI } from '@langchain/openai'
+import { HumanMessage, AIMessage, BaseMessage } from '@langchain/core/messages'
+
+// Initialize app
+const app = new MarchAgentApp({
+    gatewayUrl: process.env.GATEWAY_URL!,
+    apiKey: process.env.GATEWAY_API_KEY!,
+})
+
+// Create checkpointer for state persistence
+const checkpointer = new HTTPCheckpointSaver(app)
+
+// Define state with message accumulation
+const StateAnnotation = Annotation.Root({
+    messages: Annotation<BaseMessage[]>({
+        reducer: (x, y) => x.concat(y),
+    }),
+})
+
+// Create LLM
+const llm = new ChatOpenAI({
+    model: 'gpt-4o-mini',
+    streaming: true,
+    openAIApiKey: process.env.OPENAI_API_KEY,
+})
+
+// Define respond node
+async function respond(state: typeof StateAnnotation.State) {
+    const response = await llm.invoke(state.messages)
+    return { messages: [response] }
+}
+
+// Build graph
+const graph = new StateGraph(StateAnnotation)
+    .addNode('respond', respond)
+    .addEdge(START, 'respond')
+    .addEdge('respond', END)
+
+const compiledGraph = graph.compile({ checkpointer })
+
+async function main() {
+    const agent = await app.registerMe({
+        name: 'langgraph-agent-ts',
+        about: 'Agent using LangGraph for stateful conversations',
+        document: 'Maintains conversation state using LangGraph checkpointing.',
+    })
+
+    agent.onMessage(async (message: Message, sender: string) => {
+        // Use conversation ID as thread ID for state isolation
+        const config = { configurable: { thread_id: message.conversationId } }
+
+        // Check if we have existing state
+        const existingState = await compiledGraph.getState(config)
+
+        if (existingState && existingState.values?.messages?.length > 0) {
+            // Update existing state with new message
+            await compiledGraph.updateState(
+                config,
+                { messages: [new HumanMessage(message.content)] }
+            )
+        } else {
+            // Initialize new conversation
+            await compiledGraph.invoke({ messages: [] }, config)
+            await compiledGraph.updateState(
+                config,
+                { messages: [new HumanMessage(message.content)] }
+            )
+        }
+
+        // Stream response
+        const streamer = agent.streamer(message)
+
+        for await (const event of compiledGraph.streamEvents(null, {
+            ...config,
+            version: 'v2',
+        })) {
+            if (event.event === 'on_chat_model_stream') {
+                const content = event.data.chunk?.content
+                if (content) {
+                    streamer.stream(content as string)
+                }
+            }
+        }
+
+        await streamer.finish()
+    })
+
+    await app.run()
+}
+
+main().catch(console.error)
+```
+
+#### Vercel AI SDK Integration
+
+Use `VercelAIMessageStore` to persist message history:
+
+```typescript
+import { MarchAgentApp, Message } from '@march/agent'
+import { VercelAIMessageStore } from '@march/agent/extensions/vercel-ai'
+import { streamText, CoreMessage } from 'ai'
+import { openai } from '@ai-sdk/openai'
+
+const app = new MarchAgentApp({
+    gatewayUrl: process.env.GATEWAY_URL!,
+    apiKey: process.env.GATEWAY_API_KEY!,
+})
+
+// Create message store for persistence
+const messageStore = new VercelAIMessageStore(app)
+
+const SYSTEM_PROMPT = 'You are a helpful medical assistant.'
+
+async function main() {
+    const agent = await app.registerMe({
+        name: 'vercel-ai-agent-ts',
+        about: 'Agent using Vercel AI SDK',
+        document: 'Uses Vercel AI SDK for LLM interactions with message persistence.',
+    })
+
+    agent.onMessage(async (message: Message, sender: string) => {
+        // Load existing message history
+        const history = await messageStore.load(message.conversationId)
+
+        // Build messages array
+        const messages: CoreMessage[] = [
+            { role: 'system', content: SYSTEM_PROMPT },
+            ...history,
+            { role: 'user', content: message.content }
+        ]
+
+        const streamer = agent.streamer(message)
+        let fullResponse = ''
+
+        // Stream response using Vercel AI SDK
+        const result = await streamText({
+            model: openai('gpt-4o'),
+            messages,
+            onChunk: ({ chunk }) => {
+                if (chunk.type === 'text-delta') {
+                    streamer.stream(chunk.textDelta)
+                    fullResponse += chunk.textDelta
+                }
+            }
+        })
+
+        await streamer.finish()
+
+        // Save updated history (without system message)
+        await messageStore.save(message.conversationId, [
+            ...history,
+            { role: 'user', content: message.content },
+            { role: 'assistant', content: fullResponse }
+        ])
+    })
+
+    await app.run()
+}
+
+main().catch(console.error)
+```
+
+##### VercelAIMessageStore Methods
+
+| Method | Description |
+|--------|-------------|
+| `load(conversationId)` | Load message history for a conversation |
+| `save(conversationId, messages)` | Save message history |
+| `clear(conversationId)` | Clear message history |
+| `append(conversationId, messages)` | Append messages to existing history |
+| `getLastMessages(conversationId, count)` | Get last N messages |
+
+---
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GATEWAY_URL` | Agent Gateway address (host:port) | Required |
+| `GATEWAY_API_KEY` | API key for gateway authentication | Required |
+| `CONNECTION_SECURE` | Use TLS for connections | `false` |
+| `HEARTBEAT_INTERVAL` | Heartbeat interval in seconds | `10` |
+| `AGENT_BASE_URL` | Base URL for artifacts | `http://localhost:8060` |
+| `OPENAI_API_KEY` | OpenAI API key | Required |
+| `OPENAI_MODEL` | OpenAI model for text | `gpt-4o-mini` |
+| `OPENAI_VISION_MODEL` | OpenAI model for images | `gpt-4o` |
+| `DEBUG` | Enable debug logging | `false` |
+
+---
+
+## Running the Agent
+
+### Development Mode
+
+```bash
+# With hot reload
+pnpm dev
+```
+
+This uses `tsx watch` to automatically restart when files change.
+
+### Production Mode
+
+```bash
+# Build
+pnpm build
+
+# Run
+pnpm start
+```
+
+### With Docker
+
+Create a `Dockerfile`:
+
+```dockerfile
+FROM node:18-alpine
+
+WORKDIR /app
+
+COPY package*.json pnpm-lock.yaml ./
+RUN npm install -g pnpm && pnpm install --frozen-lockfile
+
+COPY . .
+RUN pnpm build
+
+CMD ["pnpm", "start"]
+```
+
+Build and run:
+
+```bash
+docker build -t my-agent .
+docker run --env-file .env my-agent
+```
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `@march/agent` | March Agent SDK (or local link) |
+| `@langchain/openai` | LangChain OpenAI integration |
+| `@langchain/core` | LangChain core types |
+| `dotenv` | Environment variable loading |
+
+### Optional Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `@langchain/langgraph` | LangGraph state management |
+| `@langchain/langgraph-checkpoint` | LangGraph checkpointing |
+| `ai` | Vercel AI SDK |
+| `@ai-sdk/openai` | OpenAI provider for Vercel AI |
+| `pdf-parse` | PDF text extraction |
+
+---
+
+## Troubleshooting
+
+### Environment Variables Not Loading
+
+If environment variables aren't being picked up:
+
+```typescript
+import { config } from 'dotenv'
+import { resolve } from 'path'
+
+// Use explicit path and override: true
+config({ path: resolve(process.cwd(), '.env'), override: true })
+
+// Verify loading
+console.log('OPENAI_API_KEY loaded:', !!process.env.OPENAI_API_KEY)
+```
+
+### Connection Issues
+
+If the agent can't connect to the gateway:
+
+1. Verify `GATEWAY_URL` is correct (e.g., `agent-gateway:8080` or `localhost:8080`)
+2. Ensure the gateway is running
+3. Check `CONNECTION_SECURE` matches the gateway configuration
+
+### Attachment Download Failures
+
+If attachments fail to download with 404:
+
+1. Verify the attachment service is running
+2. Check the attachment URL format in the logs
+3. Ensure the gateway is proxying `/s/attachment/*` correctly
+
+### TypeScript Errors
+
+If you see type errors with the SDK:
+
+```bash
+# Ensure you have the latest types
+pnpm add -D @types/node
+
+# Type check
+pnpm typecheck
+```
+
+---
+
+## Complete Example
+
+Here's a complete agent implementation with all features:
+
+```typescript
+import { config } from 'dotenv'
+import { resolve } from 'path'
+import { MarchAgentApp, Message } from '@march/agent'
+import { ChatOpenAI } from '@langchain/openai'
+import { HumanMessage, AIMessage, SystemMessage, BaseMessage } from '@langchain/core/messages'
+
+// Load environment
+config({ path: resolve(process.cwd(), '.env'), override: true })
+
+const SYSTEM_PROMPT = `You are a helpful assistant. Be concise and helpful.`
+
+// Initialize LLMs
+const llm = new ChatOpenAI({
+    model: process.env.OPENAI_MODEL || 'gpt-4o-mini',
+    streaming: true,
+    openAIApiKey: process.env.OPENAI_API_KEY,
+})
+
+const visionLlm = new ChatOpenAI({
+    model: process.env.OPENAI_VISION_MODEL || 'gpt-4o',
+    streaming: true,
+    openAIApiKey: process.env.OPENAI_API_KEY,
+})
+
+// Initialize app
+const app = new MarchAgentApp({
+    gatewayUrl: process.env.GATEWAY_URL || 'agent-gateway:8080',
+    apiKey: process.env.GATEWAY_API_KEY || 'agent-key',
+    heartbeatInterval: parseInt(process.env.HEARTBEAT_INTERVAL || '10'),
+    secure: process.env.CONNECTION_SECURE === 'true',
+})
+
+async function main() {
+    // Register agent
+    const agent = await app.registerMe({
+        name: 'complete-agent-ts',
+        about: 'A complete TypeScript agent example',
+        document: 'Demonstrates all SDK features including history, attachments, and streaming.',
+        representationName: 'Complete Agent (TS)',
+        baseUrl: process.env.AGENT_BASE_URL || 'http://localhost:8060',
+        metadata: { version: '1.0.0' },
+    })
+
+    // Handle all messages
+    agent.onMessage(async (message: Message, sender: string) => {
+        const messages: BaseMessage[] = [new SystemMessage(SYSTEM_PROMPT)]
+
+        // Load conversation history
+        if (message.conversation) {
+            const history = await message.conversation.getAgentHistory({ limit: 20 })
+            for (const msg of history) {
+                if (msg.role === 'user') {
+                    messages.push(new HumanMessage(msg.content))
+                } else {
+                    messages.push(new AIMessage(msg.content))
+                }
+            }
+        }
+
+        // Handle attachments
+        let selectedLlm = llm
+        if (message.hasAttachment() && message.attachment) {
+            const attachment = message.attachment
+
+            if (attachment.contentType?.startsWith('image/')) {
+                // Image attachment - use vision model
+                selectedLlm = visionLlm
+                try {
+                    const base64Image = await message.getAttachmentBase64()
+                    messages.push(new HumanMessage({
+                        content: [
+                            { type: 'text', text: message.content || 'Describe this image' },
+                            {
+                                type: 'image_url',
+                                image_url: { url: `data:${attachment.contentType};base64,${base64Image}` },
+                            },
+                        ],
+                    }))
+                } catch (e) {
+                    messages.push(new HumanMessage(
+                        `${message.content}\n\n[Image could not be processed: ${attachment.filename}]`
+                    ))
+                }
+            } else if (attachment.contentType === 'application/pdf') {
+                // PDF attachment
+                messages.push(new HumanMessage(
+                    `${message.content}\n\nA PDF was attached: ${attachment.filename} (${Math.round((attachment.size || 0) / 1024)} KB)`
+                ))
+            } else {
+                // Other attachment
+                messages.push(new HumanMessage(
+                    `${message.content}\n\nFile attached: ${attachment.filename}`
+                ))
+            }
+        } else {
+            // Text-only message
+            messages.push(new HumanMessage(message.content))
+        }
+
+        // Create streamer with metadata
+        const streamer = agent.streamer(message)
+        streamer.setMessageMetadata({
+            model: selectedLlm === visionLlm ? 'gpt-4o' : 'gpt-4o-mini',
+            hasAttachment: message.hasAttachment(),
+        })
+
+        // Stream response
+        try {
+            const stream = await selectedLlm.stream(messages)
+            for await (const chunk of stream) {
+                if (chunk.content) {
+                    streamer.stream(chunk.content as string)
+                }
+            }
+        } catch (e) {
+            streamer.stream('I encountered an error. Please try again.')
+        }
+
+        await streamer.finish()
+    })
+
+    // Start agent
+    console.log('Starting agent...')
+    await app.run()
+}
+
+main().catch((error) => {
+    console.error('Failed to start agent:', error)
+    process.exit(1)
+})
+```
+
+---
+
+## License
+
+MIT