Overview

Freeplay 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.

Use this SDK to integrate with Freeplay's core capabilities:

• Prompts — version, format, and fetch prompt templates across environments
• Recording — log LLM calls for observability and debugging
• Sessions & Traces — group interactions and multi-step agent workflows
• Test Runs — execute evaluation runs against prompts/datasets
• Feedback — capture user/customer feedback and events

Requirements

• Node.js 18 or higher
• A Freeplay account + API key

Installation

npm install freeplay

Quick Start

import Freeplay from "freeplay";

const freeplay = new Freeplay({
  freeplayApiKey: process.env.FREEPLAY_API_KEY,
});

// Fetch a prompt from Freeplay
const prompt = await freeplay.prompts.getFormatted({
  projectId: process.env.FREEPLAY_PROJECT_ID,
  templateName: "my-prompt",
  environment: "prod",
  variables: { user_input: "Hello, world!" },
});

// Call your LLM provider with prompt.llmPrompt
const response = await openai.chat.completions.create({
  model: prompt.promptInfo.model,
  messages: prompt.llmPrompt,
});

// Record the result for observability
await freeplay.recordings.create({
  projectId: process.env.FREEPLAY_PROJECT_ID,
  allMessages: prompt.allMessages({
    role: "assistant",
    content: response.choices[0].message.content,
  }),
});

See the SDK Setup guide for complete examples.

Configuration

Environment variables

export FREEPLAY_API_KEY="fp_..."
export FREEPLAY_PROJECT_ID="xy..."
# Optional: override if using a custom domain / private deployment
export FREEPLAY_API_BASE="https://app.freeplay.ai/api"

API base URL
Default: https://app.freeplay.ai/api

Custom domain/private deployment: https://<your-domain>/api

Versioning

This SDK follows Semantic Versioning (SemVer): MAJOR.MINOR.PATCH.

• PATCH: bug fixes
• MINOR: backward-compatible features
• MAJOR: breaking changes

Before upgrading major versions, review the changelog.

Support

• Docs: https://docs.freeplay.ai
• Issues: https://github.com/freeplayai/freeplay-node/issues
• Security: [email protected]

Contributing

See CONTRIBUTING.md.

License

Apache-2.0 — see LICENSE.