Capture Traces

Capture is the first step of the Agent Skills workflow. A Trace is the record of one bounded task attempt. Zep compiles Skills only from Traces, so the quality of the capture controls the quality of the Skills. For a complete example, see the Agent Skills quickstart.

If your agent already sends traces to Braintrust or LangSmith, you can import those traces as Traces instead of new capture code.

Create a Trace

The task_family_source field reports how Agent Skills assigned the task family: declared means you supplied it, import_rule means an import mapping supplied it, and inferred means Agent Skills assigned it. The task_family_inference field reports the inference state: pending, assigned, or unassigned. When the state is unassigned, Agent Skills could not assign a task family. Compilation does not use a Trace that has no task family. To give the Trace a task family after you close it, use client.agent.trace.correct_task_family.

A BYOM configuration requires task_family. A strict-residency deployment requires task_family. In either case, the API returns 400 with code invalid_request and message task_family is required when the request omits it.

Use trace_id to retry a Trace create request. When the create parameters match, Zep returns 200 with the existing Trace. When they differ, Zep returns 409.

Limits

Each Trace can accept up to 1,024 events. Event content can contain up to 64 KiB. A tool_result event can contain up to 1 MiB. An append event request returns 400 if an event exceeds a limit or if it would exceed the event limit.

The objective must be at most 8 KiB (8,192 bytes). The create request does not check this size. When the objective is larger, each append event request for the Trace returns 400.

A task_family slug has 1 to 128 characters. It must match ^[a-z0-9][a-z0-9._/-]{0,127}$: use lowercase letters, digits, ., _, /, or -, and start with a lowercase letter or digit. A create request with an invalid slug returns 400.

Append events

Append the events in the order that they occur. Each event has an event_type and usually a content string.

Record decisions and the reasons for them. The compiler uses decision events to write the decision points of a Skill. A Trace that has only tool calls and results gives a less useful procedure.

Set context on an event to give the model, the tools, and the environments that the agent used. A compiled Skill can name a model, a tool, or an environment only when the event context of a cited Trace contains that value.

Skills learning reads context and does not read metadata. Put the tool name in context.tools. A tool event with no tool name is valid, for example when the tool name is private or not known.

Link a tool result to its call

Set tool_call_id on a tool_call event and on its tool_result event to link the result to its call. Use the call ID that your agent framework already gives the call:

Send the same value on the call and on its result. tool_call_id is valid only on tool_call and tool_result events. A result with no matching call is valid. When an agent calls the same tool two times in one turn, the call ID tells the compiler which result belongs to which call. An imported trace gets tool_call_id from the call ID in the source trace. When a tool span in the source trace has no valid call ID, Zep uses the span ID. A valid ID is not blank and is at most 256 bytes. When the span ID is also not valid, the event has no tool_call_id.

from zep_cloud import AgentTraceEventContext, AgentTraceResourceRef
tool_context = AgentTraceEventContext(tools=[AgentTraceResourceRef(name="search_orders")])
client.agent.trace.append_event(
    agent_uuid=agent_uuid,
    trace_uuid=trace_uuid,
    event_type="tool_call",
    content='search_orders(customer_id="c-118")',
    context=tool_context,
    tool_call_id="call_8f2b",
)
client.agent.trace.append_event(
    agent_uuid=agent_uuid,
    trace_uuid=trace_uuid,
    event_type="tool_result",
    content="Two orders: 5521 shipped, 5530 pending.",
    context=tool_context,
    tool_call_id="call_8f2b",
)

To retry a failed append safely, set event_id to your own identifier for the event. When you send the same event_id again, Zep returns the existing event and does not add a second event. For the other optional event fields, see the API reference.

Close a Trace

Close the Trace when the attempt ends. The close request sets the outcome and the verification strength.

Zep compiles Skills only from successful attempt families with strong verification. The strong values are tool, customer, and external. Zep keeps Traces with other values, but does not compile Skills from them.

For strong verification, send one of these fields:

• verifier: an inline verifier with verifier_id, class, and optional outcome, assertion_id, and evidence_reference. The class is necessary the first time that the Agent receives the verifier_id. Zep then registers the verifier. Later requests can omit class. If a later request sends a different class, the API returns a conflict.
• verifier_id: the ID of a verifier that you registered for the Agent.

If the request has strong verification and no verifier, the API returns 400 with the message verifier is required for this verification strength.

The close request returns 202 Accepted. Zep summarizes the Trace in the background.

Sequence gaps

When a close request includes missing_sequence_ranges, it must also include reason. A reason without missing_sequence_ranges returns 400. If the Trace has unacknowledged event sequences, close returns 409 with the missing ranges in missing_sequence_ranges. Too many ranges also return 409.

Use the SDK close method to acknowledge the ranges:

client.agent.trace.close(
    agent_uuid=agent_uuid,
    trace_uuid=trace_uuid,
    outcome="succeeded",
    missing_sequence_ranges=[{"first": 2, "last": 3}],
    reason="The agent confirmed that these events were not sent.",
)

Retries

A retry is a new Trace with parent_trace_uuid set to the earlier attempt. The initial attempt and its retries are one attempt family. Zep counts attempt families, not Traces, when it decides if it has sufficient evidence to compile or admit a Skill. Ten retries of one failed task are one attempt family.

Close each attempt with its own outcome. Reopen a closed Trace only when you need to correct that attempt, not to start a retry. Reopening returns the Trace to the open state and increases its revision. The Trace is not eligible for learning while it is open. When you close it again, Zep creates a new summary version.

Idempotency

Trace and event writes accept an optional Idempotency-Key header. The value must be a UUIDv4.

The SDK sends a new key for each call. When the SDK retries a call, it sends the same key again.

If your code can retry a logical write, for example after a timeout, do these steps:

1. Create one UUIDv4 key for the write.
2. Pass the key with the idempotency key option of the first call.
3. Pass the same key on each retry.

Correct or remove captured data

Use these operations to correct or remove data after capture. When an operation changes the evidence of a Skill, Zep repairs the affected summaries and Skills in the background.

The correction, deletion, and revocation requests need the current revision of the Trace or the verifier as expected_revision. An evidence invalidation request names the verifier revisions that gave the incorrect results.

Other Trace operations