Import Traces from LangSmith

If your agent already sends traces to LangSmith, Zep can import those LangSmith traces as Traces. You do not have to add capture code to the agent first. Imported Traces go through the same summary, compilation, admission, and retrieval steps as captured Traces. An import does not create or admit a Skill directly.

You can do these steps in the Dashboard or with the SDK. In the Dashboard, add the LangSmith credential in the project settings under Trace Connections. Then open the Agent and add an import.

How an import works

1. A trace connection stores one LangSmith credential for the project. Zep verifies the credential before it stores it, and Zep never returns the credential.
2. A Trace import selects LangSmith traces for one Agent. A one-time import reads a list of trace IDs or the traces that match a filter. A scheduled import reads new traces that match a filter at a fixed interval.
3. A mapping tells Zep how to set the task family, the objective, and the outcome of each Trace from the trace data.
4. Each run of the import creates or updates one Trace for each LangSmith trace.

Connect LangSmith

Use a LangSmith service key or personal access token with read access to the workspaces that you will import. If the credential can read workspaces from more than one LangSmith organization, verification fails with HTTP 400 Bad Request. Make sure that all of its workspaces belong to one organization.

import os
from zep_cloud.client import Zep
client = Zep(api_key=os.environ["ZEP_API_KEY"])
connection = client.trace_connection.create(
    provider="langsmith",
    name="Production LangSmith",
    credential=os.environ["LANGSMITH_API_KEY"],
    requests_per_minute=10,
)
# Store connection.uuid_ in your application database.
project = next(
    p
    for p in client.trace_connection.project.list(connection.uuid_)
    # Use "<workspace display name> / support-agent" when the key can read more than one workspace.
    if p.name == "support-agent"
)

The project list is paged. The SDK reads the next pages when you iterate. A project is a LangSmith tracing project. Its ID is <workspace_id>:<project_id>. When the credential can read more than one workspace, Zep prefixes each project name with <workspace display name> / . Use the full name when you select a project. If you change the credential later, the new credential must belong to the same organization. Zep returns HTTP 409 Conflict if it belongs to a different organization.

LangSmith uses https://api.smith.langchain.com by default. Pass api_url when you create a connection. Zep stores this value in settings.api_url. Set it to https://eu.api.smith.langchain.com to use the EU region, or set it to the HTTPS API URL of a self-hosted LangSmith deployment. The URL must have a host and must not include user information, a query string, or a fragment. The host must resolve to a public IP address.

The connection setting requests_per_minute limits requests to LangSmith. Zep stores this value in settings.requests_per_minute. It defaults to 10 and accepts values from 1 to 60.

Map LangSmith traces to Traces

The mapping object sets the Trace fields from each LangSmith trace:

LangSmith feedback provides trace scores. Zep uses the feedback key as the score name and the feedback score as its value. Numeric scores from 0 to 1 are supported. Boolean scores map to 1 or 0. Zep ignores a score outside this range. If a trace has more than one feedback item with the same key, Zep uses the item that changed last.

In these examples, agent is an Agent that you created, as in the quickstart.

Use a LangSmith feedback score that your evaluation already computes. Set score_verifier to true to make the score an external verification. Then a successful run can support a Skill and increase its trust. Without score_verifier, a score rule sets agent verification, and Zep does not compile Skills from those Traces. A Trace with outcome unknown gives a summary, but it gives weak evidence for admission. For more about outcomes and verification, see Capture Traces.

To test a mapping before you save an import, read one trace with the mapping. The preview field of the response shows the task family, objective, outcome, and verification that the mapping gives. If the run will skip the trace, preview shows the skip reason.

mapping = {
    "task_family": {"source": "fixed", "value": "billing.support"},
    "objective": {"source": "first_user_message"},
    "outcome": [
        {
            "rule": "score",
            "name": "resolution",
            "succeeded_at_or_above": 0.8,
            "failed_below": 0.4,
        }
    ],
    "score_verifier": True,
}
preview = client.trace_connection.trace.get(
    connection.uuid_,
    provider_project_id=project.id,
    trace_id="trace-123",
    mapping=mapping,
)

To find trace IDs, list the traces of a project with trace_connection.trace.list. The list accepts filters for start time, tags, exact trace name, error state, root metadata, and scores. The tags_all filter requires every tag. The tags_any filter requires at least one tag. Metadata filters use exact matches. Score filters use a score name and an optional minimum or maximum value.

Import traces one time

A one-time import starts a run immediately. Use it to learn from a set of traces that you selected. Send up to 1,000 trace IDs, or send a filter instead of trace_ids. A filter must contain started_after, started_before, or both.

once = client.agent.trace_import.create(
    agent.uuid_,
    name="Billing backfill",
    connection_uuid=connection.uuid_,
    provider_project_id=project.id,
    selection={"trace_ids": ["trace-123", "trace-456"]},
    mapping=mapping,
)

Import new traces on a schedule

A scheduled import keeps learning from production traffic without a change to the agent. An import with a schedule is a scheduled import. The filter must contain a time bound, as in a one-time import, but the runs do not use that bound. start_from sets the earliest start time of the traces that the runs read. Each run reads the traces that match the other filter fields and that changed after the previous run. After a trace closes, Zep waits for settle_minutes with no new activity before it imports the trace.

An online scorer can add a score after a trace closes. Set settle_minutes to a time that is longer than the scorer delay. If Zep imports a trace before its score arrives, the Trace has no score verification, and Zep does not compile Skills from it. To also use a score that arrives after the import, set on_source_change="replace" on the import. Then the next run replaces the Trace when the source trace changes. The default value, ignore, keeps the first Trace.

scheduled = client.agent.trace_import.create(
    agent.uuid_,
    name="Billing production",
    connection_uuid=connection.uuid_,
    provider_project_id=project.id,
    selection={"filter": {"started_after": "2026-10-01T00:00:00Z", "tags_all": ["production"]}},
    schedule={"interval_hours": 4, "start_from": "now", "settle_minutes": 60, "max_open_hours": 24},
    mapping=mapping,
)
# Store scheduled.import_.uuid_ in your application database.

The schedule has these fields:

• interval_hours: 1, 4, 12, or 24.
• start_from: now or an RFC 3339 time. now is the time when you create the import. To also import earlier traces, set start_from to a time in the past.
• settle_minutes: the time, from 0 to 1,440 minutes, that a closed trace must have no new activity before Zep imports it. If you do not set this field, the value is 0.
• max_open_hours: the maximum time, from 1 to 168 hours, that Zep waits for an open trace. This field is required.

To start a run before the next interval, call agent.trace_import.run.create.

Check the results

Each run reports counts of the traces that it imported, updated, skipped, or could not import, and a count for each skip reason. Use agent.trace_import.run.list and agent.trace_import.run.get to read the runs. Use agent.trace_import.run.item.list to read the result and the reason for each trace. A skip is a decision of a mapping rule, for example a trace with no task family. A skip is not an error.

To list the Traces of one import, call agent.trace.list with import_uuid. Then follow the learning state of the Agent, as you do for captured Traces.

Review imported evidence

Imported Traces follow the approval settings of the Agent. To require human review for each candidate that uses evidence from one import, set require_review=True on the import. This rule applies also when the Agent approval is auto. For more about approval, see Configure Learning and Admission.

Pause or delete an import

• To stop the scheduled runs, call agent.trace_import.pause.
• To start the scheduled runs again, call agent.trace_import.resume.
• To delete the import and keep its Traces, call agent.trace_import.delete.
• To delete the import and its Traces, call agent.trace_import.delete with traces="delete".

When you delete an import, Zep keeps its Traces by default. When you set traces="delete", Zep deletes them asynchronously. When you delete a trace connection, Zep keeps all of the imported Traces.

Trace connection and import operations