API Docs

Everything you need to integrate CastMyAgent personas into your AI agents, copilots, and automated workflows.

Production File Format

Every talent package includes a persona.json production file — the core asset that defines the character's identity, personality, model configuration, and voice settings.

{
  "personaId": "barry-compliance-specialist",
  "version": "1.0.0",
  "name": "Barry",
  "title": "IT Compliance & GRC Specialist",
  "provider": "CastMyAgent — castmyagent.ai",
  "compatibility": [
    "claude-opus-4-6",
    "claude-sonnet-4-5-20250929",
    "gpt-4o",
    "gemini-2.0-flash"
  ],
  "config": {
    "temperature": 0.7,
    "top_p": 0.9,
    "max_tokens": 2048
  },
  "identity": {
    "shortBio": "Barry is the human equivalent of a security awareness popup...",
    "personality": ["Methodical", "Earnest", "Unflappable"],
    "communicationStyle": "Flat Midwestern American communication style
      with methodical, earnest, unflappable energy.",
    "quirks": [
      "Cites a framework before answering any request",
      "Signs every message with full name, title, department,
        extension, and legal disclaimer",
      "Uses 'I'll need to loop in Legal on that' as a reflex"
    ],
    "accentBackground": "Flat Midwestern American",
    "skills": [
      { "id": "audit-processes", "label": "Audit Processes" },
      { "id": "write-policies", "label": "Write Policies" },
      { "id": "enforce-compliance", "label": "Enforce Compliance" },
      { "id": "assess-risk", "label": "Assess Risk" },
      { "id": "write-reports", "label": "Write Reports" }
    ]
  },
  "voice": {
    "provider": "elevenlabs",
    "stability": 0.75,
    "similarityBoost": 0.85,
    "style": 0.4,
    "speakerBoost": true
  },
  "systemPromptFile": "system-prompt.md",
  "avatarFile": "headshot.jpg",
  "voiceSampleFile": "voice-reel.mp3"
}

System Prompt Structure

Each package includes a system-prompt.md file — a fully structured system prompt with character identity, behavioral encoding, specialties, and actionable skills. This is the file you paste into your agent's system instructions.

# Character: Barry
## Role: IT Compliance & GRC Specialist
## Department: Compliance Corner

You are Barry, an IT compliance & GRC specialist. Barry is the human
equivalent of a security awareness popup...

## Communication Style
- Accent/Background: Flat Midwestern American
- Core traits: Methodical, Earnest, Unflappable
- Always stay in character. Your responses should reflect your
  background and expertise naturally.

## Behavioral Encoding
- Cites a framework before answering any request
- Signs every message with full name, title, department, extension,
  and legal disclaimer
- Uses 'I'll need to loop in Legal on that' as a reflex
- Gets genuinely enthusiastic about audit trails
- Refers to himself in the third person when citing policy

## Specialties
- NIST frameworks
- Audit trails
- Policy enforcement
- Risk assessment
- Compliance documentation

## Actionable Skills
- Audit Processes: Conduct thorough audits of business processes
- Write Policies: Draft and maintain organizational policies
- Enforce Compliance: Monitor and enforce regulatory compliance
- Assess Risk: Evaluate and quantify organizational risk
- Write Reports: Create detailed reports and documentation

## Guidelines
- Respond as Barry would — with the communication patterns,
  vocabulary, and cadence matching your background.
- Draw on your specialties when relevant, while remaining
  approachable and clear.
- Your personality traits should come through naturally in how
  you frame responses.
- Never break character unless explicitly asked.

Deploying to a Claude Agent

Pass the system prompt to the Anthropic API via the system parameter. Use the config values from persona.json for model settings.

import Anthropic from "@anthropic-ai/sdk";
import { readFileSync } from "fs";
import persona from "./persona.json";

const systemPrompt = readFileSync("./system-prompt.md", "utf-8");
const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-sonnet-4-5-20250929",
  max_tokens: persona.config.max_tokens,    // 2048
  system: systemPrompt,
  messages: [
    { role: "user", content: "Review this SOC 2 audit report." }
  ],
});

Deploying to a GPT Agent

Use the system prompt as the first message in the OpenAI chat completions API or paste it into a custom GPT's instructions.

import OpenAI from "openai";
import { readFileSync } from "fs";
import persona from "./persona.json";

const systemPrompt = readFileSync("./system-prompt.md", "utf-8");
const client = new OpenAI();

const completion = await client.chat.completions.create({
  model: "gpt-4o",
  temperature: persona.config.temperature,   // 0.7
  top_p: persona.config.top_p,               // 0.9
  max_tokens: persona.config.max_tokens,     // 2048
  messages: [
    { role: "system", content: systemPrompt },
    { role: "user", content: "Review this SOC 2 audit report." }
  ],
});

Deploying to a Gemini Agent

Pass the system prompt via the systemInstruction parameter in the Google Generative AI SDK.

import { GoogleGenerativeAI } from "@google/generative-ai";
import { readFileSync } from "fs";
import persona from "./persona.json";

const systemPrompt = readFileSync("./system-prompt.md", "utf-8");
const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

const model = genAI.getGenerativeModel({
  model: "gemini-2.0-flash",
  systemInstruction: systemPrompt,
  generationConfig: {
    temperature: persona.config.temperature,  // 0.7
    topP: persona.config.top_p,               // 0.9
    maxOutputTokens: persona.config.max_tokens // 2048
  }
});

const result = await model.generateContent(
  "Review this SOC 2 audit report."
);

Using with Agent Frameworks

CastMyAgent personas work with any agent framework that accepts system prompts. The system-prompt.md file contains everything the agent needs to stay in character — personality, behavioral quirks, specialties, and actionable skills.

LangChain

import { ChatAnthropic } from "@langchain/anthropic";
import { SystemMessage, HumanMessage } from "@langchain/core/messages";
import { readFileSync } from "fs";

const systemPrompt = readFileSync("./system-prompt.md", "utf-8");

const model = new ChatAnthropic({
  model: "claude-sonnet-4-5-20250929",
  temperature: 0.7,
});

const response = await model.invoke([
  new SystemMessage(systemPrompt),
  new HumanMessage("Draft a data retention policy for our company."),
]);

Vercel AI SDK

import { anthropic } from "@ai-sdk/anthropic";
import { generateText } from "ai";
import { readFileSync } from "fs";

const systemPrompt = readFileSync("./system-prompt.md", "utf-8");

const { text } = await generateText({
  model: anthropic("claude-sonnet-4-5-20250929"),
  system: systemPrompt,
  prompt: "Draft a data retention policy for our company.",
});

Voice Configuration

Walk-on packages include a voice-config.json file with synthesis settings (stability, similarity, style). A voiceId is included only when a real ElevenLabs ID is assigned — the field is omitted when none exists. When a reel is included, use voice-reel.mp3 as the character reference. Voice parameters are automatically tuned based on the character's personality — calm characters get higher stability, energetic characters get more expressive style.

{
  "provider": "elevenlabs",
  "model_id": "eleven_multilingual_v2",
  "voice_settings": {
    "stability": 0.82,
    "similarity_boost": 0.85,
    "style": 0.25,
    "use_speaker_boost": true
  },
  "accent_notes": "Flat Midwestern American"
}

Platform-Specific Quickstart Files

Walk-on packages include a quickstart/ folder with ready-to-use config files for each platform — no manual formatting needed. These files use the same full character brief as system-prompt.md.

FilePlatformHow to Use
quickstart/claude-code/CLAUDE.mdClaude CodeDrop into project root — Claude Code reads it automatically
quickstart/gpt/instructions.mdCustom GPTPaste contents into the Custom GPT Instructions field
quickstart/gemini/system-instructions.mdGoogle AI StudioPaste contents as System Instructions in AI Studio

Walk-on Package Contents

Walk-on downloads include the full package. The only paid product on the site is the optional Executive Producer Pass. Live zips contain the files below:

FileIncluded
persona.json
headshot.jpg
system-prompt.md
voice-config.json
quickstart/ (3 files)
voice-reel.mp3When a reel exists
README.md (call sheet)

persona.json Schema Reference

FieldTypeDescription
personaIdstringUnique slug derived from name + title
versionstringSemver version of the persona file
namestringCharacter's first name
titlestringJob title / role
providerstringAlways "CastMyAgent — castmyagent.ai"
compatibilitystring[]Tested model IDs (Claude, GPT, Gemini)
configobjectRecommended temperature, top_p, max_tokens
identityobjectPersonality, skills, quirks, communication style
voiceobjectElevenLabs voice settings (stability, style, boost)

Supported Models

Every persona is tested against and compatible with these models:

Claude

  • claude-opus-4-6
  • claude-sonnet-4-5-20250929

GPT

  • gpt-4o
  • Custom GPTs

Gemini

  • gemini-2.0-flash
  • Google AI Studio

Partner API

Agent platforms can integrate CastMyAgent as a character layer via our Partner API. Authenticate with an API key and retrieve personas in platform-native formats.

Authentication

Include your API key in the x-api-key header with every request. Become a partner to get your key.

GET /api/partners/catalog

Returns the full persona catalog. Supports optional ?department=ENGINEERING filter.

curl -H "x-api-key: your-key" \
  https://castmyagent.ai/api/partners/catalog

// Response
{
  "partner": "your-platform",
  "count": 19,
  "personas": [
    {
      "slug": "barry-compliance-specialist",
      "name": "Barry",
      "title": "IT Compliance & GRC Specialist",
      "department": "COMPLIANCE_CORNER",
      "personality": ["Methodical", "Earnest", "Unflappable"],
      "compatibility": ["claude", "gpt", "gemini"],
      "bookingRate": "FREE",
      "tagline": "..."
    },
    ...
  ]
}

GET /api/partners/personas/{slug}

Returns a single persona in the requested format. Use the ?format= query parameter to specify the output format.

FormatDescription
raw (default)Full persona.json + system prompt
claude-codeCLAUDE.md format for Claude Code projects
gptCustom GPT instructions format
geminiGemini / Google AI Studio system instructions
openai-apiOpenAI API message format (system message object)
anthropic-apiAnthropic API format (system parameter string)
curl -H "x-api-key: your-key" \
  "https://castmyagent.ai/api/partners/personas/barry-compliance-specialist?format=openai-api"

// Response
{
  "partner": "your-platform",
  "slug": "barry-compliance-specialist",
  "name": "Barry",
  "format": "openai-api",
  "message": {
    "role": "system",
    "content": "# Character: Barry\n## Role: IT Compliance & GRC Specialist\n..."
  },
  "config": {
    "temperature": 0.7,
    "top_p": 0.9,
    "max_tokens": 2048
  },
  "media": {
    "headshot": "https://...",
    "voiceReel": "https://...",
    "attribution": "Character by CastMyAgent (castmyagent.ai)"
  }
}

Note: Walk-on personas are available via the Partner API. The Executive Producer Pass is the live paid product.

Need Help?

If you have questions about integrating CastMyAgent personas into your agents or workflows, reach out at support@castmyagent.ai.

Ready to integrate?

Browse the roster, book a character, and deploy to your agent.

Browse the Roster