Capture Trajectories | Zep Documentation

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

Create a Trajectory

Field	Required	Description
`objective`	Yes	The goal of this task instance
`task_family`	Yes	A slug for the kind of task, for example `billing.support`. Use the same value for all attempts at the same kind of task.
`trajectory_id`	No	Your identifier for the Trajectory
`parent_trajectory_uuid`	No	The Trajectory that this attempt retries
`learn_from`	No	Set to `false` to keep the Trajectory out of compilation. The default value is `true`.
`metadata`	No	A JSON object of your own data

Choose task families that are specific enough to share one procedure. Zep compiles, admits, and filters Skills by task family. Two different tasks in one task family can give a Skill that applies to neither task.

Append events

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

Event type	Use for
`input_reference`	The task input or a reference to it
`observation`	A fact that the agent found
`decision`	A choice that the agent made and the reason for it
`tool_call`	A call that the agent made to a tool
`tool_result`	The result of a tool call
`artifact`	An output that the agent produced, for example a reply or a file
`checkpoint`	A milestone in the task
`feedback`	Feedback from a user or a reviewer
`correction`	A change to an earlier step after an error
`reflection`	The agent’s own review of its work
`verification`	The result of a check on the work

Record decisions and the reasons for them. The compiler uses decision events to write the decision points of a Skill. A Trajectory 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 Trajectory contains that value.

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 Trajectory

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

`outcome`	Meaning
`succeeded`	The task is complete and correct
`partial`	Some of the task is complete
`failed`	The task did not complete
`abandoned`	The agent or the user stopped the task
`unknown`	The result is not known

`verification`	Meaning	Verifier
`none`	No check confirmed the outcome	Not required
`agent`	The agent reports the outcome	Not required
`tool`	A tool or a test confirmed the outcome	Required
`customer`	The customer confirmed the outcome	Required
`external`	An external system confirmed the outcome	Required

Zep compiles Skills only from successful attempt families with strong verification. The strong values are tool, customer, and external. Zep keeps Trajectories 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 Trajectory in the background.

Retries

A retry is a new Trajectory with parent_trajectory_uuid set to the earlier attempt. The initial attempt and its retries are one attempt family. Zep counts attempt families, not Trajectories, 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. Do not reopen a closed Trajectory.

Idempotency

Trajectory and event writes accept an optional Idempotency-Key header. The value must be a UUIDv4. Use a new key for each logical write, and send the same key again when you retry that write.

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.

Operation	Use when
`client.agent.trajectory.correct_task_family`	A closed Trajectory has the wrong task family.
`client.agent.trajectory.delete_event`	An event contains data that Zep must not keep. Zep removes the event content before the response.
`client.agent.trajectory.delete`	Zep must not keep any event of the Trajectory.
`client.agent.verifier.revoke`	You do not trust the later results of a verifier. The verifier cannot send new assertions after revocation.
`client.agent.verifier.invalidate_evidence`	A verifier gave incorrect results in the past. Zep removes the Skills that depend on that evidence from search until it repairs them.

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