Skip to main content

aip_sdk.trace_tags

Trace-tag authoring for agent-trace dataset versions.

Trace tags are per-trace (or per-row) key -> value annotations overlaid onto the canonical trace view at read time — labels, review verdicts, or any metadata you want to attach to a trace without mutating the immutable dataset version. Each tag is keyed on (target_ref, key) and upserts last-write-wins.

aip_sdk.trace_tags.MAX_TRACE_TAGS_PER_REQUEST​

aip_sdk.trace_tags.MAX_TRACE_TAGS_PER_REQUEST = 1000

No docstring is defined in the source.

aip_sdk.trace_tags.TagInput​

aip_sdk.trace_tags.TagInput = TraceTagUpsert | dict[str, object]

No docstring is defined in the source.

aip_sdk.trace_tags.TraceTag​

aip_sdk.trace_tags.TraceTag

A persisted trace tag returned by the platform.

aip_sdk.trace_tags.TraceTag.created_at​

aip_sdk.trace_tags.TraceTag.created_at: datetime | None = None

No docstring is defined in the source.

aip_sdk.trace_tags.TraceTag.id​

aip_sdk.trace_tags.TraceTag.id: str

No docstring is defined in the source.

aip_sdk.trace_tags.TraceTag.key​

aip_sdk.trace_tags.TraceTag.key: str

No docstring is defined in the source.

aip_sdk.trace_tags.TraceTag.model_config​

aip_sdk.trace_tags.TraceTag.model_config = ConfigDict(extra='allow')

No docstring is defined in the source.

aip_sdk.trace_tags.TraceTag.target_ref​

aip_sdk.trace_tags.TraceTag.target_ref: str

No docstring is defined in the source.

aip_sdk.trace_tags.TraceTag.value​

aip_sdk.trace_tags.TraceTag.value: str | None = None

No docstring is defined in the source.

aip_sdk.trace_tags.TraceTagUpsert​

aip_sdk.trace_tags.TraceTagUpsert

A single trace tag to write.

A value of None records a presence-only tag (the key is set with no value).

aip_sdk.trace_tags.TraceTagUpsert.key​

aip_sdk.trace_tags.TraceTagUpsert.key: str = Field(min_length=1, max_length=128)

No docstring is defined in the source.

aip_sdk.trace_tags.TraceTagUpsert.model_config​

aip_sdk.trace_tags.TraceTagUpsert.model_config = ConfigDict(extra='forbid')

No docstring is defined in the source.

aip_sdk.trace_tags.TraceTagUpsert.target_ref​

aip_sdk.trace_tags.TraceTagUpsert.target_ref: str = Field(min_length=1, max_length=255)

No docstring is defined in the source.

aip_sdk.trace_tags.TraceTagUpsert.value​

aip_sdk.trace_tags.TraceTagUpsert.value: str | None = Field(default=None, max_length=512)

No docstring is defined in the source.

aip_sdk.trace_tags.coerce_tag​

aip_sdk.trace_tags.coerce_tag(tag: TagInput) -> TraceTagUpsert

Validate a tag input into a TraceTagUpsert.

Parameters

Returns

Raises

aip_sdk.trace_tags.delete_trace_tag​

aip_sdk.trace_tags.delete_trace_tag(dataset_id: str, version_id: str, *, target_ref: str, key: str, client: APIClient | None = None) -> None

Delete a single trace tag by its (target_ref, key) identity.

Idempotent: deleting a tag that does not exist succeeds silently.

Parameters

  • dataset_id str: Dataset ID.
  • version_id str: Dataset version ID.
  • target_ref str: The trace/row reference the tag annotates.
  • key str: The tag key to delete.
  • client APIClient | None: Optional API client.

Raises

  • AuthError: If credentials are missing or invalid.
  • ForbiddenError: If the caller lacks editor rights on the version's workspace.
  • NotFoundError: If the dataset version does not exist, or belongs to a workspace the caller is not a member of.

aip_sdk.trace_tags.list_trace_tags​

aip_sdk.trace_tags.list_trace_tags(dataset_id: str, version_id: str, *, target_ref: str | None = None, client: APIClient | None = None) -> list[TraceTag]

List trace tags on a dataset version.

Parameters

  • dataset_id str: Dataset ID.
  • version_id str: Dataset version ID.
  • target_ref str | None: Optional trace/row reference to scope the results to a single target.
  • client APIClient | None: Optional API client.

Returns

  • list[TraceTag]: The version's trace tags, optionally scoped to target_ref.

Raises

  • AuthError: If credentials are missing or invalid.
  • NotFoundError: If the dataset version does not exist, or belongs to a workspace the caller is not a member of.
  • ResponseParseError: If the platform's response does not match this SDK version.

aip_sdk.trace_tags.upsert_trace_tags​

aip_sdk.trace_tags.upsert_trace_tags(dataset_id: str, version_id: str, tags: Iterable[TagInput], *, client: APIClient | None = None) -> list[TraceTag]

Create or update trace tags on a dataset version.

Tags upsert on (target_ref, key) — writing an existing pair replaces its value.

Parameters

  • dataset_id str: Dataset ID.
  • version_id str: Dataset version ID the tags annotate.
  • tags Iterable[TagInput]: Tags to write, as TraceTagUpsert instances or equivalent dicts. Must contain between 1 and MAX_TRACE_TAGS_PER_REQUEST items.
  • client APIClient | None: Optional API client.

Returns

  • list[TraceTag]: The persisted tags, one per input tag.

Raises

  • InvalidArgumentError: If tags is empty, malformed, or exceeds the per-request limit.
  • AuthError: If credentials are missing or invalid.
  • ForbiddenError: If the caller lacks editor rights on the version's workspace.
  • NotFoundError: If the dataset version does not exist, or belongs to a workspace the caller is not a member of.
  • ResponseParseError: If the platform's response does not match this SDK version.