Skip to main content
POST
https://sandbox.open-metadata.org/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"
    ],
    prompt="Focus on data quality best practices and recommend specific test types."
))
print(f"Created agent: {agent.name} (ID: {agent.id})")

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "DataQualityPlannerAgent",
  "display_name": "Data Quality Planner",
  "description": "Analyzes tables and recommends data quality tests",
  "persona": "DataAnalyst",
  "api_enabled": true,
  "abilities": [
    "search_metadata",
    "get_entity_details",
    "get_entity_lineage"
  ],
  "prompt": "Focus on data quality best practices and recommend specific test types.",
  "provider": "openai",
  "created_at": "2025-06-15T10:30:00Z",
  "updated_at": "2025-06-15T10:30:00Z"
}

​
Create Agent

Programmatically create an AI Studio Agent. Each agent combines a persona, a set of abilities, and full access to OpenMetadata into a ready-to-use assistant you can invoke from any SDK.

​
Body Parameters

​
name
string
required
Unique name for the agent. Used as the identifier in API calls (e.g., DataQualityPlannerAgent). Must be alphanumeric with no spaces.
​
description
string
required
A short description of what the agent does. This is displayed in the AI Studio UI and returned in list responses.
​
persona
string
required
Name of the persona to assign to this agent. The persona defines the agent’s behavior and personality. Must reference an existing persona.
​
display_name
string
Human-readable display name for the agent. If omitted, defaults to name.
​
api_enabled
boolean
default:"false"
Whether the agent can be invoked via the API. Set to true to allow SDK and CLI access.
​
abilities
array
List of ability names to enable for the agent. Abilities determine what tools and actions the agent can use.
​
prompt
string
Additional system prompt appended to the persona’s base prompt. Use this to provide agent-specific instructions without creating a new persona.
​
provider
string
default:"openai"
LLM provider to use for the agent. Supported values: openai, anthropic, azure_openai.
​
bot_name
string
Name of the OpenMetadata bot whose credentials the agent uses. If omitted, uses the default 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"
    ],
    prompt="Focus on data quality best practices and recommend specific test types."
))
print(f"Created agent: {agent.name} (ID: {agent.id})")

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "DataQualityPlannerAgent",
  "display_name": "Data Quality Planner",
  "description": "Analyzes tables and recommends data quality tests",
  "persona": "DataAnalyst",
  "api_enabled": true,
  "abilities": [
    "search_metadata",
    "get_entity_details",
    "get_entity_lineage"
  ],
  "prompt": "Focus on data quality best practices and recommend specific test types.",
  "provider": "openai",
  "created_at": "2025-06-15T10:30:00Z",
  "updated_at": "2025-06-15T10:30:00Z"
}

​
Returns

Returns the created AgentInfo object with all specified properties and system-generated fields.

​
Response

​
id
string
Unique identifier for the agent (UUID format).
​
name
string
Agent name used in API calls.
​
display_name
string
Human-readable display name.
​
description
string
Description of the agent.
​
persona
string
Name of the assigned persona.
​
api_enabled
boolean
Whether the agent is accessible via the API.
​
abilities
array
List of enabled ability names.
​
prompt
string
Additional system prompt for the agent.
​
provider
string
LLM provider used by the agent.
​
created_at
string
ISO 8601 timestamp of when the agent was created.
​
updated_at
string
ISO 8601 timestamp of when the agent was last updated.

​
List Agents

Retrieve all API-enabled AI Studio Agents available in your OpenMetadata instance.
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} (API: {agent.api_enabled})")

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "DataQualityPlannerAgent",
      "display_name": "Data Quality Planner",
      "description": "Analyzes tables and recommends data quality tests",
      "persona": "DataAnalyst",
      "api_enabled": true,
      "abilities": ["search_metadata", "get_entity_details", "get_entity_lineage"],
      "provider": "openai"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "name": "SqlQueryAgent",
      "display_name": "SQL Query Agent",
      "description": "Generates and explains SQL queries based on your metadata",
      "persona": "SqlExpert",
      "api_enabled": true,
      "abilities": ["search_metadata", "get_entity_details"],
      "provider": "openai"
    }
  ]
}

​
Error Handling

CodeError TypeDescription
400BAD_REQUESTInvalid request body, missing required fields, or invalid ability names
401UNAUTHORIZEDInvalid or missing authentication token
403FORBIDDENUser lacks permission to create agents
404PERSONA_NOT_FOUNDThe referenced persona does not exist
409ENTITY_ALREADY_EXISTSAn agent with the same name already exists