{"id":34524874,"url":"https://github.com/dpguthrie/ai-sdk-multi-turn-example","last_synced_at":"2026-05-28T15:31:42.950Z","repository":{"id":318758435,"uuid":"1076458003","full_name":"dpguthrie/ai-sdk-multi-turn-example","owner":"dpguthrie","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-14T22:38:44.000Z","size":29952,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-15T02:46:05.922Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dpguthrie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-14T22:21:50.000Z","updated_at":"2025-10-14T22:38:47.000Z","dependencies_parsed_at":"2025-10-15T06:36:36.703Z","dependency_job_id":"44b70b92-1031-47a5-b145-72cc6947d650","html_url":"https://github.com/dpguthrie/ai-sdk-multi-turn-example","commit_stats":null,"previous_names":["dpguthrie/ai-sdk-multi-turn-example"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dpguthrie/ai-sdk-multi-turn-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpguthrie%2Fai-sdk-multi-turn-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpguthrie%2Fai-sdk-multi-turn-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpguthrie%2Fai-sdk-multi-turn-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpguthrie%2Fai-sdk-multi-turn-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dpguthrie","download_url":"https://codeload.github.com/dpguthrie/ai-sdk-multi-turn-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpguthrie%2Fai-sdk-multi-turn-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27995843,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T05:07:01.062Z","updated_at":"2025-12-24T05:07:03.082Z","avatar_url":"https://github.com/dpguthrie.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI SDK Multi-Turn Tracing with Braintrust\n\nThis repository demonstrates how to implement multi-turn conversation tracing using the [Vercel AI SDK](https://sdk.vercel.ai/) and [Braintrust](https://www.braintrust.dev/) for comprehensive observability and debugging of AI applications.\n\n## 🎥 Demo\n\n\u003ca href=\"https://share.cleanshot.com/1q2JKdH0\" title=\"AI SDK Demo\"\u003e\u003cimg src=\"https://github.com/dpguthrie/ai-sdk-multi-turn-example/blob/main/demo.png\" alt=\"Screenshot\" /\u003e\u003c/a\u003e\n\n## 🚀 Features\n\n- **Multi-turn conversations** with conversation history tracking\n- **Tool calling** with weather API simulation\n- **Automatic tracing** of all AI SDK interactions\n- **Input/output logging** for each conversation turn\n- **Conversation ID tracking** for session management\n- **CLI interface** for interactive testing\n\n## 📋 Prerequisites\n\n- Node.js 18+ \n- OpenAI API key\n- Braintrust API key\n\n## 🛠️ Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/dpguthrie/ai-sdk-multi-turn-example.git\ncd ai-sdk-multi-turn-example\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Create a `.env` file with your API keys:\n```env\nOPENAI_API_KEY=sk-your-openai-api-key\nBRAINTRUST_API_KEY=your-braintrust-api-key\n```\n\n## 🏃‍♂️ Usage\n\nStart the chatbot:\n```bash\nnpm start\n# or\nnpx tsx chatbot.ts\n```\n\nThe chatbot will:\n1. Initialize a Braintrust project called \"ai-sdk-example\"\n2. Generate a unique conversation ID\n3. Start an interactive CLI session\n4. Automatically trace all interactions\n\n### Example Interaction\n\n```\nChatbot ready! Conversation ID: 123e4567-e89b-12d3-a456-426614174000\nType your message (or \"exit\" to quit):\n\nYou: What's the weather like in San Francisco?\nAssistant: I'll check the weather in San Francisco for you.\n\nThe weather in San Francisco is 22°C and sunny.\n\nYou: How about New York?\nAssistant: Let me get the current weather for New York.\n\nThe weather in New York is 18°C and cloudy.\n```\n\n## 🏗️ Architecture\n\n### Key Components\n\n1. **Braintrust Integration**\n   - `initLogger()` - Initialize Braintrust project\n   - `wrapAISDK()` - Wrap AI SDK functions for automatic tracing\n   - `traced()` - Manual span creation for custom logic\n\n2. **AI SDK Integration**\n   - `generateText()` - Core text generation with tool support\n   - Tool definitions with Zod schemas\n   - Multi-step conversation handling\n\n3. **Tracing Strategy**\n   - Each conversation turn wrapped in a `traced` span\n   - Input/output logging for debugging\n   - Conversation ID tracking across turns\n   - Tool call tracing\n\n### Code Structure\n\n```typescript\n// Initialize Braintrust\ninitLogger({\n  projectName: 'ai-sdk-example',\n  apiKey: process.env.BRAINTRUST_API_KEY,\n});\n\n// Wrap AI SDK for automatic tracing\nconst { generateText } = wrapAISDK(ai);\n\n// Manual tracing for conversation turns\nreturn traced(\n  async (span) =\u003e {\n    // Log input state\n    span.log({ input: messages, metadata: { conversation_id: conversationId } });\n    \n    // AI SDK call with tools\n    const result = await generateText({\n      model: openai('gpt-4o-mini'),\n      messages: messages,\n      tools: { /* tool definitions */ },\n    });\n    \n    // Log output state\n    span.log({ output: [...messages] });\n    \n    return text;\n  },\n  { name: 'chat-turn', type: 'task' }\n);\n```\n\n## 📚 Documentation Links\n\n### Vercel AI SDK\n- [Getting Started](https://sdk.vercel.ai/docs/getting-started)\n- [generateText API](https://sdk.vercel.ai/docs/reference/ai/generate-text)\n- [Tool Calling](https://sdk.vercel.ai/docs/guides/tools)\n- [Multi-step Conversations](https://sdk.vercel.ai/docs/guides/multi-step)\n\n### Braintrust\n- [Quick Start](https://www.braintrust.dev/docs/getting-started)\n- [Tracing Guide](https://www.braintrust.dev/docs/guides/tracing)\n- [AI SDK Integration](https://www.braintrust.dev/docs/guides/ai-sdk)\n- [Span API Reference](https://www.braintrust.dev/docs/reference/span)\n\n### OpenAI\n- [API Reference](https://platform.openai.com/docs/api-reference)\n- [GPT-4o Mini](https://platform.openai.com/docs/models/gpt-4o-mini)\n\n## 🔧 Configuration\n\n### Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `OPENAI_API_KEY` | Your OpenAI API key | ✅ |\n| `BRAINTRUST_API_KEY` | Your Braintrust API key | ✅ |\n\n### Model Configuration\n\nThe example uses `gpt-4o-mini` for cost-effective conversations. You can modify the model in `chatbot.ts`:\n\n```typescript\nconst result = await generateText({\n  model: openai('gpt-4o-mini'), // Change to 'gpt-4o', 'gpt-4', etc.\n  // ...\n});\n```\n\n## 🎯 Tracing Features\n\n### What Gets Traced\n\n- **Input/Output**: Each conversation turn's messages\n- **Tool Calls**: Weather API calls with parameters and results\n- **Model Interactions**: All AI SDK generateText calls\n- **Conversation Flow**: Multi-turn conversation history\n- **Metadata**: Conversation IDs, timestamps, and custom data\n\n### Braintrust Dashboard\n\nAfter running conversations, view traces in your [Braintrust dashboard](https://www.braintrust.dev/app):\n\n1. Navigate to your \"ai-sdk-example\" project\n2. View conversation traces with input/output data\n3. Analyze tool call performance\n4. Debug conversation flows\n\n## 🛠️ Development\n\n### Adding New Tools\n\n1. Define the tool function:\n```typescript\nconst myTool = async ({ param }: { param: string }) =\u003e {\n  // Tool logic\n  return result;\n};\n```\n\n2. Add to the tools object:\n```typescript\ntools: {\n  myTool: {\n    description: 'Tool description',\n    inputSchema: z.object({\n      param: z.string().describe('Parameter description'),\n    }),\n    execute: myTool,\n  },\n}\n```\n\n### Custom Tracing\n\nFor custom tracing beyond AI SDK calls:\n\n```typescript\nreturn traced(\n  async (span) =\u003e {\n    span.log({ metadata: {custom_data: 'value'} });\n    // Your custom logic\n    return result;\n  },\n  { name: 'custom-operation', type: 'task' }\n);\n```\n\n## 📦 Dependencies\n\n- **@ai-sdk/openai**: OpenAI provider for AI SDK\n- **ai**: Vercel AI SDK core\n- **braintrust**: Observability and tracing platform\n- **zod**: Schema validation for tool parameters\n- **dotenv**: Environment variable management\n- **tsx**: TypeScript execution\n- **@types/node**: Node.js type definitions\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test with `npm start`\n5. Submit a pull request\n\n## 🔗 Links\n\n- [Vercel AI SDK Documentation](https://sdk.vercel.ai/)\n- [Braintrust Documentation](https://www.braintrust.dev/docs)\n- [OpenAI API Documentation](https://platform.openai.com/docs)\n- [Zod Documentation](https://zod.dev/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdpguthrie%2Fai-sdk-multi-turn-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdpguthrie%2Fai-sdk-multi-turn-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdpguthrie%2Fai-sdk-multi-turn-example/lists"}