> For the complete documentation index, see [llms.txt](https://developer.collibra.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.collibra.com/tutorials/collibra-ai-agent-python-integration.md).

# 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](https://pypi.org/project/requests/).
* You have [created](https://productresources.collibra.com/docs/collibra/latest/Default.htm#cshid=DOC0655) a programmatic user for API requests that has at least the **AI Business User** global role.
* You have [obtained the ID](https://productresources.collibra.com/docs/collibra/latest/Default.htm#cshid=DOC1092) of the **AI Governance** domain.

  <div data-gb-custom-block data-tag="hint" data-style="success" class="hint hint-success"><p>The ID of the <strong>AI Governance</strong> domain should be <code>00000000-0000-0000-0000-000000006023</code>.</p></div>

## Code sample

```python
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](https://github.com/collibra/documentation/tree/publish/developer/api/guides/import-api/import-api.md): learn how the Collibra Import API processes JSON payloads.
* [Importing assets via JSON](https://github.com/collibra/documentation/tree/publish/developer/api/guides/import-api/import-api/import-commands/importing-assets.md): reference for the asset import command format.
* [Importing complex relations via JSON](https://github.com/collibra/documentation/tree/publish/developer/api/guides/import-api/import-api/import-commands/importing-complex-relations.md): reference for the complex relation import command format, used by the AI Agent Deployment in this script.
* [Create your own Collibra REST API client](/tutorials/create-your-own-collibra-rest-api-client.md): learn how to use the OpenApi Generator to create a Python REST API client.
* Read the [AI Governance documentation](https://productresources.collibra.com/docs/collibra/latest/Content/AIGovernance/co_about-ai-governance.htm).