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, and model configuration.

{
  "personaId": "barry-compliance-specialist",
  "version": "1.0.0",
  "name": "Barry",
  "title": "IT Compliance & GRC Specialist",
  "provider": "CastMyAgent — castmyagent.ai",
  "compatibility": [
    "claude",
    "gpt",
    "gemini"
  ],
  "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": "Midwestern American background, flat and procedural writing",
    "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" }
    ]
  },
  "systemPromptFile": "system-prompt.md",
  "avatarFile": "headshot.jpg",
  "voiceSampleFile": "voice-reel.mp3"
}

Some packages include a reference clip used when writing the persona. It is background material only. It does not make the agent speak, and the audio is not loaded as speech.

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
- Background: Midwestern American background, flat and procedural writing
- 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 and
  vocabulary 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.",
});

Reference files

Some packages include a notes file (voice-config.json) and, when one exists, a reference clip (voice-reel.mp3). They are background material for the write-up only. The agent answers in text. The audio is not loaded as speech, and it does not make the agent speak.

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. Live zips contain the files below:

FileIncluded
persona.json✓
headshot.jpg✓
system-prompt.md✓
voice-config.json✓
quickstart/ (3 files)✓
voice-reel.mp3When a reference clip exists
README.md (call sheet)✓
LICENSEMIT License for the text files

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
voiceobjectNotes on writing tone and pacing. Text only. Not loaded as speech.

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.

License

Persona text returned by the Partner API is Free Persona Pack Text Files under the MIT License. API access, keys, and rate limits stay under our Terms of Service. The attribution field is a request, not a condition of the MIT License. Headshots and audio are Reserved Items.

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://...",
    // voiceReel is a reference clip for the write-up. It does not make the agent speak.
    "attribution": "Character by CastMyAgent (castmyagent.ai)"
  }
}

Note: Walk-on personas are available via the Partner API.

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