Publish inventory with the Python SDK¶

Use this when Trust3 cannot discover your AI assets for you — agents you built yourself, or anything else that is code rather than a registered cloud resource. You add the Trust3 collector SDK to your own application, describe your agents, tools and models, and push that description to Trust3. They appear in the portal under AI Assets, ready for policies.

This is useful on its own. Publishing an inventory gives you the asset list, ownership and policy coverage, with no trace collection involved. If you also want to see each agent's real activity, monitoring adds that on top later — it needs more from your runtime plane, and you do not need any of it to get started here.

This is a change to your application code. Nothing is configured in the portal for it.

Before you begin¶

You need a runtime plane, because that is where the API key comes from — but only for the key. Basic Config is enough, and it is the shorter path: three steps, no storage, DNS, ingress or IAM role.

Step 1 — Install the SDK¶

1

pip3 install trust3-ai-collector-sdk

Step 2 — Decide what to publish¶

You publish a snapshot: a set of assets plus the relationships between them.

Asset kinds¶

Relationship kinds¶

Using a kind outside these values is rejected by governance with an HTTP 422.

Step 3 — Write the publish code¶

The snapshot below is not a standalone script you run once by hand. It belongs in your application's startup path, so the inventory refreshes every time you deploy — see When to run it.

To try it first, put it in a file such as publish_inventory.py, set the API key it reads, and run it directly:

1
2

export TRUST3_API_KEY=<your runtime plane API key>
python3 publish_inventory.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

import json, os
from trust3_ai_collector_sdk import (
    Asset, AssetKind,
    InventoryClient, InventoryClientConfig,
    InventorySnapshot,
    Relationship, RelationshipKind,
)

snap = InventorySnapshot(
    source="my_platform",          # namespaces every asset id
    account="prod.example.com",    # the deployment this inventory describes
    vendor="Acme Corp",
    product_name="My Platform",
    environment="prod",            # dev / test / stage / prod
)

snap.assets += [
    Asset(
        kind=AssetKind.AGENT,
        id="billing_agent",
        name="Billing Agent",          # ← the name traces are matched on
        description="Answers billing questions",
        owners=["ops-team@example.com"],
        provider="openai",
        model_name="gpt-4o",
        properties={
            # The topics this agent is allowed to answer on — see below
            "provenance_json": json.dumps({"categories": ["billing", "customer_support"]}),
        },
    ),
    Asset(kind=AssetKind.MODEL, id="openai:gpt-4o", name="gpt-4o", provider="openai"),
    Asset(kind=AssetKind.TOOL, id="lookup_invoice", name="lookup_invoice"),
]

snap.relationships += [
    Relationship(kind=RelationshipKind.USES_MODEL,
                 from_id="billing_agent", from_kind=AssetKind.AGENT,
                 to_id="openai:gpt-4o",   to_kind=AssetKind.MODEL),
    Relationship(kind=RelationshipKind.CAN_INVOKE,
                 from_id="billing_agent",  from_kind=AssetKind.AGENT,
                 to_id="lookup_invoice",   to_kind=AssetKind.TOOL),
]

config = InventoryClientConfig(
    api_key=os.environ["TRUST3_API_KEY"],
)

with InventoryClient(config) as client:
    result = client.submit(snap)
    print(f"{result.assets_pushed} assets, {result.relationships_pushed} relationships "
          f"— status={result.status} governance={result.governance_status}")

Keep source and account stable¶

They namespace every id you publish, so an agent with id billing_agent becomes my_platform:prod.example.com:ai_agent:billing_agent in governance.

Changing either one creates a parallel set of assets rather than updating the existing ones. Pick values you can keep, and use environment to distinguish dev from prod rather than changing account.

Name your agents carefully¶

The name field is what monitoring matches traces against, so:

• give each agent a unique name
• use the same string in your tracing configuration
• avoid renaming an agent unless you also change the tracing side at the same time

Step 4 — Declare the topics an agent may answer on¶

provenance_json is where you declare an agent's allowed scope: a list of topics it is expected to answer on. Anything outside that list can be flagged as off-topic.

1

"provenance_json": json.dumps({"categories": ["billing", "customer_support"]})

It is a JSON document stored as text inside the properties map, which is why it is wrapped in json.dumps(...) rather than written as a plain list.

The categories are free text — you choose the vocabulary. There is no fixed list and nothing validates them, so two rules follow:

• Use the same strings your policy uses. Matching is exact, so project managemant will never match project management. A typo silently produces wrong verdicts rather than an error.
• Describe what the agent is for. Everything not covered by the list becomes off-topic, so an over-narrow list flags legitimate traffic.

When to run it¶

A snapshot is a full, idempotent push — governance upserts what it receives, so re-sending the same snapshot is safe and changes nothing.

The recommended pattern is to push on application startup, once your agent registry is built. That keeps the inventory current without any scheduling of its own, and a renamed or retired agent is reflected the next time you deploy.

Make the push non-fatal. Governance being unreachable should never stop your application from booting:

1
2
3
4
5

try:
    with InventoryClient(config) as client:
        result = client.submit(snap)
except Exception:
    logger.warning("Trust3 inventory push failed", exc_info=True)   # carry on booting

Gate it behind a flag, so the same image runs unchanged in environments that should not publish — for example a TRUST3_AI_COLLECTOR_ENABLED variable, checked alongside the host and key before doing anything.

Handle errors¶

1
2
3
4
5
6
7
8

from trust3_ai_collector_sdk.errors import InventoryValidationError, InventoryTransportError

try:
    result = client.submit(snap)
except InventoryValidationError as e:
    print(f"rejected (HTTP {e.status_code}): {e.response_text}")
except InventoryTransportError as e:
    print(f"failed after retries: {e}")

InventoryValidationError means governance rejected the payload — the message tells you what was wrong. InventoryTransportError means the request never succeeded after the SDK's automatic retries.

Verify¶

1. Run your application, or the standalone script.
2. Check the printed result. It reports how many assets and relationships were pushed and the governance HTTP status; a 2xx means governance accepted them.
3. In the Trust3 portal, open AI Assets. Your agents, tools, and models appear there, one row per asset, named with the name you published.

If assets appear, your inventory is published. To see real activity against these assets, continue with Monitoring flowing against them.

Troubleshooting¶