Push API
The Push API allows you to upload your agent traces to your Explorer account in a programmatic way.
Data Types
PushTracesRequest
The PushTracesRequest class holds the request data for a trace upload request.
messages List[List[Dict]]
This represents the traces in a dataset. Each List[Dict] is a single trace within the dataset. Each dict is a single message within a trace - these can represet a user prompt, a tool call, a tool output, etc.
Must be in the required trace format. Must not be empty.
annotations Optional[List[List[AnnotationCreate]]
The annotations to push to the Invariant API.
Must be the same length as messages if provided. Must be a list of lists of AnnotationCreate type if provided.
dataset Optional[str]
The dataset name.
If None, the traces are uploaded as snippets (traces not attached to any dataset).
If you specify a dataset which doesn't exist, a new dataset is created.
metadata Optional[List[Dict]]
The metadata to attach to each uploaded trace.
Must be a list of dictionaries if provided and must be the same length as messages if provided.
Each metadata dictionary can have arbitrary keys and values for storing additional information about the trace.
See File Uploads for more information on metadata.
AnnotationCreate
The AnnotationCreate class holds the data for an annotation to be created.
See Annotations for more information on annotations.
content str
The content of the annotation.
address str
The address of the annotation.
extra_metadata Optional[Dict[Any, Any]]
Additional metadata for the annotation.
Each metadata dictionary can have arbitrary keys and values for storing additional information about the annotation.
PushTracesResponse
The PushTracesResponse class holds the response data from the PushTraces API.
id List[str]
The list of IDs for the created traces.
dataset Optional[str]
The dataset name. Default is None.
Pushing Traces
There are two SDK methods to push traces: push_trace and create_request_and_push_trace. The former accepts the PushTracesRequest type as an argument and the latter accepts Python-native types as arguments.
push_trace
The push_trace method is used to push trace data to the Invariant API using a pre-constructed request object.
request PushTracesRequest
The request object containing trace data.
request_kwargs Optional[Dict[str, Any]]
Additional keyword arguments to pass to the requests method. Default is None.
Return Value
PushTracesResponse
The response object from the Invariant API.
Example
from invariant_sdk.client import Client from invariant_sdk.types.push_traces import PushTracesRequest client = Client() request = PushTracesRequest( messages=[ [ {"role": "user", "content": "one"}, {"role": "assistant", "content": "two \n three"}, ] ], annotations=[ [ { "content": "annotating one", "address": "messages[0].content:L0", "extra_metadata": {"key1": "value1"}, } ] ], metadata=[{"meta_key_1": "meta_value_1"}], dataset="dataset_name" ) response = client.push_trace(request)
create_request_and_push_trace
The create_request_and_push_trace method is used to push trace data to the Invariant API. It creates a request object from the provided messages, annotations, and metadata, and then pushes this data to the API.
messages List[List[Dict]]
The messages to push to the Invariant API.
annotations Optional[List[List[Dict]]
The annotations to push to the Invariant API. Default is None.
metadata Optional[List[Dict]]
The metadata to push to the Invariant API. Default is None.
dataset Optional[str]
The dataset name. Default is None. If None, the traces are uploaded as snippets which are not attached to any dataset. If you specify a dataset which doesn't exist, then the API creates the dataset.
request_kwargs Optional[Mapping]
Additional keyword arguments to pass to the requests method. Default is None.
Return Value
PushTracesResponse
The response object from the Invariant API.
Example
from invariant_sdk.client import Client client = Client() messages = [ [ {"role": "user", "content": "one"}, {"role": "assistant", "content": "two \n three"}, ] ] annotations = [ [ { "content": "annotating one", "address": "messages[0].content:L0", "extra_metadata": {"key1": "value1"}, } ] ] metadata = [{"meta_key_1": "meta_value_1"}] response = client.create_request_and_push_trace( messages=messages, annotations=annotations, metadata=metadata, dataset="dataset_name" )