Skip to main content
POST
https://sandbox.getcollate.io/api
/
api
/
v1
/
agents
/
personas
POST
from ai_sdk import AISdk, AISdkConfig
from ai_sdk.models import CreatePersonaRequest

config = AISdkConfig.from_env()
client = AISdk.from_config(config)

persona = client.create_persona(CreatePersonaRequest(
    name="DataAnalyst",
    description="A meticulous data analyst focused on data quality",
    prompt=(
        "You are an expert data analyst working with Collate. "
        "You specialize in analyzing table schemas, identifying data quality issues, "
        "and recommending appropriate tests. Always reference specific columns and "
        "provide actionable recommendations. Use the available MCP tools to look up "
        "metadata before making suggestions."
    ),
    display_name="Data Analyst",
))
print(f"Created persona: {persona.name}")

{
  "name": "DataAnalyst",
  "displayName": "Data Analyst",
  "description": "A meticulous data analyst focused on data quality",
  "prompt": "You are an expert data analyst working with Collate. You specialize in analyzing table schemas, identifying data quality issues, and recommending appropriate tests. Always reference specific columns and provide actionable recommendations. Use the available MCP tools to look up metadata before making suggestions.",
  "provider": "openai",
  "createdAt": "2025-07-15T10:00:00Z",
  "updatedAt": "2025-07-15T10:00:00Z"
}

​
Create Persona

A persona defines the behavioral instructions and personality of an AI Studio Agent. Each persona contains a system prompt that shapes how the agent responds to user queries. Multiple agents can share the same persona, making it easy to standardize behavior across different agent configurations.

​
Body Parameters

​
name
string
required
Unique identifier for the persona. Used when assigning the persona to an agent. Must be alphanumeric with no spaces.
​
description
string
required
Short description of the persona’s role and behavior. Shown in the AI Studio UI.
​
prompt
string
required
System prompt that defines the persona’s behavior, tone, and instructions. This prompt is prepended to every conversation the agent has.
​
display_name
string
Human-readable display name for the persona. Defaults to name if not provided.
​
provider
string
default:"openai"
Default LLM provider for agents using this persona. One of: openai, anthropic, azure_openai. Can be overridden at the agent level.
POST
from ai_sdk import AISdk, AISdkConfig
from ai_sdk.models import CreatePersonaRequest

config = AISdkConfig.from_env()
client = AISdk.from_config(config)

persona = client.create_persona(CreatePersonaRequest(
    name="DataAnalyst",
    description="A meticulous data analyst focused on data quality",
    prompt=(
        "You are an expert data analyst working with Collate. "
        "You specialize in analyzing table schemas, identifying data quality issues, "
        "and recommending appropriate tests. Always reference specific columns and "
        "provide actionable recommendations. Use the available MCP tools to look up "
        "metadata before making suggestions."
    ),
    display_name="Data Analyst",
))
print(f"Created persona: {persona.name}")

{
  "name": "DataAnalyst",
  "displayName": "Data Analyst",
  "description": "A meticulous data analyst focused on data quality",
  "prompt": "You are an expert data analyst working with Collate. You specialize in analyzing table schemas, identifying data quality issues, and recommending appropriate tests. Always reference specific columns and provide actionable recommendations. Use the available MCP tools to look up metadata before making suggestions.",
  "provider": "openai",
  "createdAt": "2025-07-15T10:00:00Z",
  "updatedAt": "2025-07-15T10:00:00Z"
}

​
Response

​
name
string
Unique identifier for the persona.
​
displayName
string
Human-readable display name.
​
description
string
Description of the persona’s role and behavior.
​
prompt
string
The full system prompt that defines the persona’s behavior.
​
provider
string
Default LLM provider for agents using this persona.
​
createdAt
string
ISO 8601 timestamp of when the persona was created.
​
updatedAt
string
ISO 8601 timestamp of the last update.

​
List Personas

Retrieve all personas available in your Collate instance. GET /api/v1/agents/personas/
GET
from ai_sdk import AISdk, AISdkConfig

config = AISdkConfig.from_env()
client = AISdk.from_config(config)

personas = client.list_personas()

for persona in personas:
    print(f"{persona.name}: {persona.description}")
    print(f"  Prompt: {persona.prompt[:80]}...")

[
  {
    "name": "DataAnalyst",
    "displayName": "Data Analyst",
    "description": "A meticulous data analyst focused on data quality",
    "prompt": "You are an expert data analyst working with Collate...",
    "provider": "openai"
  },
  {
    "name": "SqlExpert",
    "displayName": "SQL Expert",
    "description": "Generates optimized SQL queries from natural language",
    "prompt": "You are an expert SQL developer. Given a natural language question...",
    "provider": "openai"
  }
]

​
Error Handling

CodeError TypeDescription
400BAD_REQUESTInvalid request body or missing required fields
401UNAUTHORIZEDInvalid or missing JWT token
403FORBIDDENUser lacks permission to create personas
409CONFLICTPersona with the same name already exists
500INTERNAL_SERVER_ERRORInternal error during persona creation