Collibra AI agent Python integration
You can register AI agents in Collibra by creating an AI Agent asset and its full supporting hierarchy: an agent version deployed to an endpoint, the tools it can call, and the underlying model with its own version, deployment, and endpoint. Use the following Python code with the Collibra REST Import API to automate this registration and link your agents to the relevant AI use cases.
Prerequisites
You have Python version 3.
You have installed the requests module.
You have created a programmatic user for API requests that has at least the AI Business User global role.
You have obtained the ID of the AI Governance domain.
The ID of the AI Governance domain should be
00000000-0000-0000-0000-000000006023.
Code sample
import json
import requests
# Update the following variables with your own values
DOMAIN_UUID = "YOUR_DOMAIN_UUID"
USERNAME = "YOUR_USERNAME"
PASSWORD = "YOUR_PASSWORD"
# COLLIBRA / API variables
COLLIBRA_API_URL = "YOUR_COLLIBRA_ENVIRONMENT_URL"
# Asset types
AI_AGENT_TYPE_ID = "00000000-0000-0000-0000-000000031450"
AI_AGENT_VERSION_TYPE_ID = "00000000-0000-0000-0000-000000031452"
AI_AGENT_TOOL_TYPE_ID = "00000000-0000-0000-0000-000000031453"
AI_ENDPOINT_TYPE_ID = "00000000-0000-0000-0000-000000031501"
AI_BASE_MODEL_TYPE_ID = "00000000-0000-0000-0000-000000031422"
AI_MODEL_VERSION_TYPE_ID = "00000000-0000-0000-0000-000000031402"
AI_MODEL_DEPLOYMENT_TYPE_ID = "00000000-0000-0000-0000-000000031500"
# Complex relation type: links an AI Agent Version to the AI Endpoint it is deployed on
AI_AGENT_DEPLOYMENT_CR_TYPE_ID = "00000000-0000-0000-0000-000000007505"
AI_AGENT_DEPLOYMENT_LEG_VERSION_ID = "00000000-0000-0000-0000-000000007213"
AI_AGENT_DEPLOYMENT_LEG_ENDPOINT_ID = "00000000-0000-0000-0000-000000007214"
# Relation types
AGENT_HAS_VERSION_RELATION_ID = "00000000-0000-0000-0000-000000007206"
AGENT_VERSION_CALLS_TOOL_RELATION_ID = "00000000-0000-0000-0000-000000007207"
AGENT_VERSION_INVOKES_MODEL_ENDPOINT_RELATION_ID = "00000000-0000-0000-0000-000000007210"
MODEL_HAS_VERSION_RELATION_ID = "00000000-0000-0000-0000-000000077000"
MODEL_VERSION_DEPLOYED_BY_DEPLOYMENT_RELATION_ID = "00000000-0000-0000-0000-000000077001"
DEPLOYMENT_EXPOSED_THROUGH_ENDPOINT_RELATION_ID = "00000000-0000-0000-0000-000000077006"
# Attribute types
TRAFFIC_SPLIT_PERCENTAGE_ATTRIBUTE_ID = "00000000-0000-0000-0001-000500000075"
ACCESS_METHOD_ATTRIBUTE_ID = "00000000-0000-0000-0000-000000050022"
ACCESS_INSTRUCTIONS_ATTRIBUTE_ID = "00000000-0000-0000-0000-000000050023"
MODEL_ACCURACY_ATTRIBUTE_ID = "00000000-0000-0000-0000-000000000328"
MODEL_PRECISION_ATTRIBUTE_ID = "00000000-0000-0000-0000-000000000329"
MODEL_TYPE_ATTRIBUTE_ID = "00000000-0000-0000-0000-000000000334"
DESCRIPTION_ATTRIBUTE_ID = "00000000-0000-0000-0001-000500000074"
CREATION_DATE_IN_SOURCE_ATTRIBUTE_ID = "00000000-0000-0000-0000-000000000343"
INITIATING_USER_IN_SOURCE_ATTRIBUTE_ID = "00000000-0000-0000-0000-000000078001"
VERSION_ATTRIBUTE_ID = "00000000-0000-0000-0000-000000000263"
INSTRUCTIONS_ATTRIBUTE_ID = "00000000-0000-0000-0000-000000000337"
RETRAIN_CYCLE_ATTRIBUTE_ID = "00000000-0000-0000-0000-000000000335"
class CollibraAIGov:
def __init__(self):
# Unique identifier for the domain where all AI Governance assets are stored
self.domain = DOMAIN_UUID
# Base URL for the Collibra API
self.COLLIBRA_API_URL = COLLIBRA_API_URL
# Retrieve password from secrets manager
self.PASSWORD = PASSWORD
# Username for API authentication
self.USERNAME = USERNAME
def _identifier(self, name):
"""Builds a name + domain identifier, used both for assets and for relation targets."""
return {"name": name, "domain": {"id": self.domain}}
def _asset(self, type_id, name):
return {
"resourceType": "Asset",
"identifier": self._identifier(name),
"type": {"id": type_id},
"displayName": name,
"attributes": {},
"relations": {},
}
def create_agent(
self,
agent_name,
agent_endpoint_url,
model_version_name,
model_endpoint_url,
description=None,
creation_date_in_source=None,
initiating_user_in_source=None,
agent_instructions=None,
agent_version_number="1",
agent_tools=None,
model_precision="0",
model_accuracy="0",
model_type="Generative AI",
base_model_retrain_cycle="Monthly",
):
"""
Create an AI Agent and its full supporting hierarchy in the AI Governance Module:
an AI Agent Version deployed to an AI Endpoint (optionally calling one or more AI Agent
Tools), and the AI Model (Base Model + Model Version + Model Deployment + its own AI
Endpoint) that the agent version uses for inference.
Parameters:
- agent_name: Name of the AI Agent to create. A dummy AI Agent Version named
"<agent_name> v<agent_version_number>" is created and linked to it.
- agent_endpoint_url: URL where the agent itself can be invoked. An AI Endpoint is
created for it and linked to the Agent Version via an AI Agent Deployment.
- model_version_name: Name of the model version the agent uses for inference. An AI
Base Model and an "<model_version_name> v1" AI Model Version are created for it.
- model_endpoint_url: URL of the endpoint serving that model version.
- description: Human-readable description of what the agent does. Recorded on both
the AI Agent and its AI Agent Version (optional).
- creation_date_in_source: Date the agent (and its version) was created in the source
system, for example "2026-01-19" (optional).
- initiating_user_in_source: User or service account that created the agent (and its
version) in the source system, for example "bart@acme.inc" (optional). Requires
Collibra 2026.07 or later on the AI Agent Version; on older versions use
OwnerInSource instead.
- agent_instructions: Instructions given to the AI Agent Version, for example its
system prompt or triage rules (optional).
- agent_version_number: Version number recorded on the AI Agent Version's Version
attribute, and used to build its name (optional, default "1").
- agent_tools: List of AI Agent Tool names (for example MCP tools, knowledge bases)
that this agent version can call (optional). One AI Agent Tool asset is created
per entry and linked to the agent version via a "can call" relation.
- model_precision: Precision metric of the model (optional).
- model_accuracy: Accuracy metric of the model (optional).
- model_type: Type of the model (optional). Allowed values are "Generative AI",
"Classification", "Regression", "Computer Vision", "Reinforcement Learning" or
"Image Classification".
- base_model_retrain_cycle: How often the base model is retrained (optional, default
"Monthly"). Allowed values are "Daily", "Weekly", "Monthly", "Quarterly" or "Yearly".
"""
agent_version_name = f"{agent_name} v{agent_version_number}"
model_version_full_name = f"{model_version_name} v1"
model_deployment_name = f"{model_version_name} deployment"
agent_tools = agent_tools or []
agent = self._asset(AI_AGENT_TYPE_ID, agent_name)
agent["relations"][f"{AGENT_HAS_VERSION_RELATION_ID}:TARGET"] = [
self._identifier(agent_version_name)
]
if description:
agent["attributes"][DESCRIPTION_ATTRIBUTE_ID] = [{"value": description}]
if creation_date_in_source:
agent["attributes"][CREATION_DATE_IN_SOURCE_ATTRIBUTE_ID] = [{"value": creation_date_in_source}]
if initiating_user_in_source:
agent["attributes"][INITIATING_USER_IN_SOURCE_ATTRIBUTE_ID] = [{"value": initiating_user_in_source}]
agent_version = self._asset(AI_AGENT_VERSION_TYPE_ID, agent_version_name)
agent_version["relations"][f"{AGENT_VERSION_INVOKES_MODEL_ENDPOINT_RELATION_ID}:TARGET"] = [
self._identifier(model_endpoint_url)
]
agent_version["attributes"][VERSION_ATTRIBUTE_ID] = [{"value": agent_version_number}]
if description:
agent_version["attributes"][DESCRIPTION_ATTRIBUTE_ID] = [{"value": description}]
if creation_date_in_source:
agent_version["attributes"][CREATION_DATE_IN_SOURCE_ATTRIBUTE_ID] = [{"value": creation_date_in_source}]
if initiating_user_in_source:
agent_version["attributes"][INITIATING_USER_IN_SOURCE_ATTRIBUTE_ID] = [{"value": initiating_user_in_source}]
if agent_instructions:
agent_version["attributes"][INSTRUCTIONS_ATTRIBUTE_ID] = [{"value": agent_instructions}]
agent_tool_assets = [self._asset(AI_AGENT_TOOL_TYPE_ID, tool_name) for tool_name in agent_tools]
if agent_tool_assets:
agent_version["relations"][f"{AGENT_VERSION_CALLS_TOOL_RELATION_ID}:TARGET"] = [
self._identifier(tool_name) for tool_name in agent_tools
]
agent_endpoint = self._asset(AI_ENDPOINT_TYPE_ID, agent_endpoint_url)
agent_endpoint["attributes"][ACCESS_METHOD_ATTRIBUTE_ID] = [{"value": "API"}]
agent_endpoint["attributes"][ACCESS_INSTRUCTIONS_ATTRIBUTE_ID] = [{"value": agent_endpoint_url}]
agent_deployment = {
"resourceType": "Complex Relation",
"complexRelationType": {"id": AI_AGENT_DEPLOYMENT_CR_TYPE_ID},
"attributes": {
TRAFFIC_SPLIT_PERCENTAGE_ATTRIBUTE_ID: [{"value": "100"}],
},
"relations": {
f"{AI_AGENT_DEPLOYMENT_LEG_VERSION_ID}:TARGET": [self._identifier(agent_version_name)],
f"{AI_AGENT_DEPLOYMENT_LEG_ENDPOINT_ID}:TARGET": [self._identifier(agent_endpoint_url)],
},
}
base_model = self._asset(AI_BASE_MODEL_TYPE_ID, model_version_name)
base_model["attributes"][RETRAIN_CYCLE_ATTRIBUTE_ID] = [{"value": base_model_retrain_cycle}]
model_version = self._asset(AI_MODEL_VERSION_TYPE_ID, model_version_full_name)
model_version["attributes"] = {
MODEL_ACCURACY_ATTRIBUTE_ID: [{"value": model_accuracy}],
MODEL_PRECISION_ATTRIBUTE_ID: [{"value": model_precision}],
MODEL_TYPE_ATTRIBUTE_ID: [{"value": model_type}],
}
model_version["relations"][f"{MODEL_HAS_VERSION_RELATION_ID}:SOURCE"] = [
self._identifier(model_version_name)
]
model_deployment = self._asset(AI_MODEL_DEPLOYMENT_TYPE_ID, model_deployment_name)
model_deployment["relations"][f"{MODEL_VERSION_DEPLOYED_BY_DEPLOYMENT_RELATION_ID}:SOURCE"] = [
self._identifier(model_version_full_name)
]
model_deployment["relations"][f"{DEPLOYMENT_EXPOSED_THROUGH_ENDPOINT_RELATION_ID}:TARGET"] = [
self._identifier(model_endpoint_url)
]
model_endpoint = self._asset(AI_ENDPOINT_TYPE_ID, model_endpoint_url)
model_endpoint["attributes"][ACCESS_METHOD_ATTRIBUTE_ID] = [{"value": "API"}]
model_endpoint["attributes"][ACCESS_INSTRUCTIONS_ATTRIBUTE_ID] = [{"value": model_endpoint_url}]
query_payload = json.dumps([
agent,
agent_version,
*agent_tool_assets,
agent_endpoint,
agent_deployment,
base_model,
model_version,
model_deployment,
model_endpoint,
])
# Construct the file object to be sent in the request
file = {"file": ("data.json", query_payload)}
# Make a POST request to the Collibra import API
# Increase the timeout if the request takes longer
response = requests.post(
f"{self.COLLIBRA_API_URL}/rest/2.0/import/json-job",
files=file,
auth=(self.USERNAME, self.PASSWORD),
timeout=30
)
# Print the response for debugging purposes
# Consider handling the response more gracefully in a real application
print(response)
# Example usage
#if __name__ == "__main__":
# collibra = CollibraAIGov()
# result = collibra.create_agent(
# agent_name="Support Ticket Triage Agent",
# agent_endpoint_url="https://my-agent-host.example.com/agents/triage",
# model_version_name="triage-llm",
# model_endpoint_url="https://my-model-host.example.com/serving-endpoints/triage-llm",
# description="AI Agent that has a first pass at validating if a support ticket has all required "
# "information and makes sense, determines priority and triages it to the relevant "
# "team/priority queue.",
# creation_date_in_source="2026-01-19",
# initiating_user_in_source="bart@acme.inc",
# agent_instructions="Review if the description reflects the priority value selected by the customer. "
# "Triage to the relevant team according to the @product-taxonomy.md file. For teams "
# "that have different priority queues, put it in the relevant queue.",
# agent_tools=["Zendesk MCP", "RAG engine (support knowledge base)"],
# model_precision="0.95",
# model_accuracy="0.90",
# model_type="Generative AI",
# base_model_retrain_cycle="Monthly",
# )
#print(result)The script registers an AI Agent and its full hierarchy in Collibra. The resulting assets, including the AI Agent, its version, endpoint, tools, and the linked model hierarchy, appear in the Assets drop-down list in the AI Governance domain.
If you need to capture additional information about your agents, such as ownership or usage metadata on AI Agent Tools or relationships between agents that call sub-agents, contact your Collibra administrator to expand the asset characteristics.
Additional resources
Import API guide: learn how the Collibra Import API processes JSON payloads.
Importing assets via JSON: reference for the asset import command format.
Importing complex relations via JSON: reference for the complex relation import command format, used by the AI Agent Deployment in this script.
Create your own Collibra REST API client: learn how to use the OpenApi Generator to create a Python REST API client.
Read the AI Governance documentation.
Last updated
Was this helpful?