![\"version\"](\"https://img.shields.io/npm/v/freeplay.svg\")
\n ![\"License\"](\"https://img.shields.io/badge/license-Apache--2.0-blue.svg\"){kind=icon}
\n\n The official Node/TypeScript SDK for Freeplay
\n The ops platform for enterprise AI engineering teams\n
\n \n \n
\n Docs •\n Quick Start •\n SDK Setup •\n API Reference •\n Changelog •\n Contributing\n
\n\n---\n\n## Overview\n\nFreeplay is the only platform your team needs to manage the end-to-end AI application development lifecycle. It provides an integrated workflow for improving your AI agents and other generative AI products. Engineers, data scientists, product managers, designers, and subject matter experts can all review production logs, curate datasets, experiment with changes, create and run evaluations, and deploy updates.\n\nUse this SDK to integrate with Freeplay's core capabilities:\n\n- **Observability**\n - [**Sessions**](https://docs.freeplay.ai/freeplay-sdk/sessions) — group related interactions together, e.g. for multi-turn chat or complex agent interactions\n - [**Traces**](https://docs.freeplay.ai/freeplay-sdk/traces) — track multi-step agent workflows within sessions\n - [**Completions**](https://docs.freeplay.ai/freeplay-sdk/recording-completions) — record LLM interactions for observability and debugging\n - [**Customer Feedback**](https://docs.freeplay.ai/freeplay-sdk/customer-feedback) — append user feedback and events to traces and completions\n- [**Prompts**](https://docs.freeplay.ai/freeplay-sdk/prompts) — version, format, and fetch prompt templates across environments\n- [**Test Runs**](https://docs.freeplay.ai/freeplay-sdk/test-runs) — execute evaluation runs against prompts and datasets\n\n## Requirements\n\n- Node.js 18 or higher\n- A Freeplay account + API key\n\n## Installation\n\n```bash\nnpm install freeplay\n```\n\n## Quick Start\n\n```typescript\nimport Freeplay from \"freeplay\";\nimport OpenAI from \"openai\";\n\nconst fpClient = new Freeplay({\n freeplayApiKey: process.env.FREEPLAY_API_KEY,\n});\nconst openai = new OpenAI();\n\nconst projectId = process.env.FREEPLAY_PROJECT_ID;\n\n// Fetch a prompt from Freeplay\nconst formattedPrompt = await fpClient.prompts.getFormatted({\n projectId,\n templateName: \"my-prompt\",\n environment: \"prod\",\n variables: { user_input: \"Hello, world!\" },\n});\n\n// Call your LLM provider with formattedPrompt.llmPrompt\nconst response = await openai.chat.completions.create({\n model: formattedPrompt.promptInfo.model,\n messages: formattedPrompt.llmPrompt,\n});\n\n// Record the interaction for observability\nawait fpClient.recordings.create({\n projectId,\n allMessages: formattedPrompt.allMessages({\n role: \"assistant\",\n content: response.choices[0].message.content,\n }),\n});\n```\n\nSee the [SDK Setup guide](https://docs.freeplay.ai/freeplay-sdk/setup) for complete examples.\n\n## Configuration\n\n### Environment variables\n\n```bash\nexport FREEPLAY_API_KEY=\"fp_...\"\nexport FREEPLAY_PROJECT_ID=\"xy...\"\n# Optional: override if using a custom domain / private deployment\nexport FREEPLAY_API_BASE=\"https://app.freeplay.ai/api\"\n```\n\n**API base URL** \nDefault: `https://app.freeplay.ai/api`\n\nCustom domain/private deployment: `https://