Update Agent Trace | Zep Documentation

from zep_cloud import Zep
client = Zep(
    api_key="YOUR_API_KEY_HERE",
)
client.agent.trace.update(
    agent_uuid="agent_uuid",
    trace_uuid="trace_uuid",
    expected_revision=1,
    task_family="support/refund",
)

{
  "abandoned_at": "2026-01-01T00:01:00Z",
  "agent_uuid": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
  "attempt_family_uuid": "d4e5f6a7-b8c9-4d0e-9f2a-3b4c5d6e7f80",
  "closed_at": "2026-01-01T00:01:00Z",
  "created_at": "2026-01-01T00:00:00Z",
  "internal": {
    "assertion_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
    "closing_sequence": 1,
    "current_summary_version": 1,
    "last_task_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
    "next_sequence": 1,
    "processing_state": "idle"
  },
  "learn_from": true,
  "learn_from_reason": "caller_opt_out",
  "metadata": {},
  "objective": "Refund a duplicate charge.",
  "outcome": "unknown",
  "parent_trace_uuid": "c3d4e5f6-a7b8-4c9d-8e1f-2a3b4c5d6e7f",
  "revision": 1,
  "source": {
    "connection_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
    "import_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
    "imported_at": "2026-01-01T00:00:00Z",
    "kind": "trace_import",
    "provider": "braintrust",
    "provider_project_id": "project-123",
    "run_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
    "scores": {},
    "source_changed": false,
    "source_revision": "revision-1",
    "source_url": "https://example.com/traces/trace-123",
    "trace_ended_at": "2026-01-01T00:00:00Z",
    "trace_id": "provider-trace-123",
    "trace_started_at": "2026-01-01T00:00:00Z"
  },
  "status": "open",
  "task_family": "support/refund",
  "task_family_inference": {
    "assigned_at": "2026-01-01T00:00:00Z",
    "classifier_version": "task-family-classifier-v1",
    "confidence": 0.5,
    "descriptor_version": 1,
    "learning_reusable": false,
    "state": "pending"
  },
  "task_family_source": "declared",
  "trace_id": "support-001",
  "updated_at": "2026-01-01T00:00:00Z",
  "uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
  "verification": "none"
}

Authentication

AuthorizationApi-Key

Type “Api-Key” followed by a space and the project API key.

Path parameters

agent_uuidstringRequired

Agent UUID

trace_uuidstringRequired

Trace UUID

Request

Request body

expected_revisionintegerRequired>=1

The current Trace revision used for optimistic concurrency.

task_familystring or nullRequired

Replacement task-family slug. Set to null to clear it.

Response

abandoned_atstringOptional

The time the Trace was abandoned.

agent_uuidstringOptional

The service returns the owning Agent UUID.

attempt_family_uuidstringOptional

The service returns the stable retry-family identity shared by attempts.

closed_atstringOptional

The time the Trace closed.

created_atstringOptional

The time the Trace was created.

internalobjectOptional

Server-owned fields that are not part of the top-level capture contract.

learn_frombooleanOptional

The service returns whether eligible evidence may participate in learning.

learn_from_reasonstringOptional

The service returns why the Trace is not eligible for learning, when it is not eligible.

metadatamap from strings to anyOptional

Developer metadata used for exact containment filters.

objectivestringOptional

The service returns the task-instance objective captured for this attempt.

outcomeenumOptional

The service returns the task outcome that the developer recorded. Valid values are succeeded, failed, partial, abandoned, and unknown.

Allowed values:

parent_trace_uuidstringOptional

The service returns the parent attempt when this Trace is a retry.

revisionintegerOptional

The service returns the current revision for the next update or lifecycle command.

sourceobjectOptional

The source record for an imported Trace.

statusenumOptional

The service returns the current lifecycle state. Valid values are open, closing, closed, abandoned, and deleted.

Allowed values:

task_familystringOptional

The service returns the declared or assigned task-family slug, when one is available.

task_family_inferenceobjectOptional

The service returns the latest classification result. Its state is pending, assigned, or unassigned. It is absent if classification did not run for this Trace.

task_family_sourcestringOptional

The service returns how it selected the task family. Valid values are declared, import_rule, and inferred.

trace_idstringOptional

The developer may set an identifier that is unique within the Agent. A retry with the same create parameters returns 200 and the existing Trace. Different parameters return 409.

updated_atstringOptional

The time the Trace was last updated.

uuidstringOptional

The service returns the stable Trace UUID.

verificationenumOptional

The service returns how the outcome was verified. Valid values are none, agent, tool, customer, and external.

Allowed values:

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error