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

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

agent = client.create_agent(CreateAgentRequest(
    name="DataQualityPlannerAgent",
    description="Analyzes tables and recommends data quality tests",
    persona="DataAnalyst",
    display_name="Data Quality Planner",
    api_enabled=True,
    abilities=[
        "search_metadata",
        "get_entity_details",
        "get_entity_lineage",
    ],
))
print(f"Created agent: {agent.name}")

{
  "name": "DataQualityPlannerAgent",
  "displayName": "Data Quality Planner",
  "description": "Analyzes tables and recommends data quality tests",
  "persona": "DataAnalyst",
  "abilities": [
    "search_metadata",
    "get_entity_details",
    "get_entity_lineage"
  ],
  "apiEnabled": true,
  "provider": "openai",
  "createdAt": "2025-07-15T10:30:00Z",
  "updatedAt": "2025-07-15T10:30:00Z"
}

​
Create Agent

Programmatically create an AI Studio Agent with a persona, a set of abilities, and optional API access. Agents combine a persona’s behavioral instructions with Collate’s MCP tools to form purpose-built AI assistants for data teams.

​
Body Parameters

​
name
string
required
Unique identifier for the agent. Used when invoking the agent via the SDK or API. Must be alphanumeric with no spaces (use camelCase or PascalCase).
​
description
string
required
Short description of the agent’s purpose and capabilities. Shown in the AI Studio UI and returned by the list agents endpoint.
​
persona
string
required
Name of the persona to assign to this agent. The persona defines the agent’s system prompt, personality, and behavioral instructions. Must reference an existing persona.
​
display_name
string
Human-readable display name for the agent. Shown in the AI Studio UI. Defaults to name if not provided.
​
api_enabled
boolean
default:"false"
Whether the agent can be invoked via the SDK and API. Set to true to allow programmatic access.
​
abilities
array
List of MCP tool names the agent is allowed to use. If omitted, the agent can use all available tools.
​
prompt
string
Additional system prompt to append to the persona’s base prompt. Use this to add agent-specific instructions without creating a new persona.
​
provider
string
default:"openai"
LLM provider to use for this agent. One of: openai, anthropic, azure_openai.
​
bot_name
string
Name of the Collate bot whose credentials the agent uses for metadata operations. Defaults to the instance’s ingestion bot.
POST
from ai_sdk import AISdk, AISdkConfig
from ai_sdk.models import CreateAgentRequest

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

agent = client.create_agent(CreateAgentRequest(
    name="DataQualityPlannerAgent",
    description="Analyzes tables and recommends data quality tests",
    persona="DataAnalyst",
    display_name="Data Quality Planner",
    api_enabled=True,
    abilities=[
        "search_metadata",
        "get_entity_details",
        "get_entity_lineage",
    ],
))
print(f"Created agent: {agent.name}")

{
  "name": "DataQualityPlannerAgent",
  "displayName": "Data Quality Planner",
  "description": "Analyzes tables and recommends data quality tests",
  "persona": "DataAnalyst",
  "abilities": [
    "search_metadata",
    "get_entity_details",
    "get_entity_lineage"
  ],
  "apiEnabled": true,
  "provider": "openai",
  "createdAt": "2025-07-15T10:30:00Z",
  "updatedAt": "2025-07-15T10:30:00Z"
}

​
Response

​
name
string
Unique identifier for the agent.
​
displayName
string
Human-readable display name.
​
description
string
Description of the agent’s purpose.
​
persona
string
Name of the assigned persona.
​
abilities
array
List of MCP tool names the agent can use.
​
apiEnabled
boolean
Whether the agent can be invoked via the SDK and API.
​
provider
string
LLM provider used by the agent.
​
createdAt
string
ISO 8601 timestamp of when the agent was created.
​
updatedAt
string
ISO 8601 timestamp of the last update.

​
List Agents

Retrieve all API-enabled AI Studio Agents in your Collate instance. GET /api/v1/api/agents/
GET
from ai_sdk import AISdk, AISdkConfig

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

agents = client.list_agents()

for agent in agents:
    print(f"{agent.name}: {agent.description}")
    print(f"  Abilities: {', '.join(agent.abilities)}")
    print(f"  API Enabled: {agent.api_enabled}")

[
  {
    "name": "DataQualityPlannerAgent",
    "displayName": "Data Quality Planner",
    "description": "Analyzes tables and recommends data quality tests",
    "persona": "DataAnalyst",
    "abilities": [
      "search_metadata",
      "get_entity_details",
      "get_entity_lineage"
    ],
    "apiEnabled": true,
    "provider": "openai"
  },
  {
    "name": "SqlQueryAgent",
    "displayName": "SQL Query Agent",
    "description": "Generates and explains SQL queries based on your metadata",
    "persona": "SqlExpert",
    "abilities": [
      "search_metadata",
      "get_entity_details"
    ],
    "apiEnabled": true,
    "provider": "openai"
  }
]

​
Error Handling

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