> This page is for version v4 (default). > For other versions, use one of these documentation indexes: > - v4 (default): https://docs-beta.getzep.com/v4/llms.txt > - v3: https://docs-beta.getzep.com/v3/llms.txt > - v2: https://docs-beta.getzep.com/v2/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs-beta.getzep.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-beta.getzep.com/_mcp/server. # 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](/agent-skills/capture-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. **`Python`** ```python Python 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 " / support-agent" when the key can read more than one workspace. if p.name == "support-agent" ) ``` **`TypeScript`** ```typescript TypeScript import { Zep, ZepClient } from "@getzep/zep-cloud"; const client = new ZepClient({ apiKey: process.env.ZEP_API_KEY }); const connection = await client.traceConnection.create({ provider: "langsmith", name: "Production LangSmith", credential: process.env.LANGSMITH_API_KEY, requestsPerMinute: 10, }); // Store connection.uuid in your application database. let projectId: string | undefined; for await (const p of await client.traceConnection.project.list(connection.uuid!)) { // Use " / support-agent" when the key can read more than one workspace. if (p.name === "support-agent") { projectId = p.id; break; } } ``` The project list is paged. The SDK reads the next pages when you iterate. A project is a LangSmith tracing project. Its ID is `:`. When the credential can read more than one workspace, Zep prefixes each project name with ` / `. 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: | Field | Sources | Default | | ------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | `task_family` | A fixed value, a metadata key, a tag prefix, or the trace name | No default. If the source gives no value, the run skips the trace. | | `objective` | The first user message, the root input, or a metadata key | The first user message | | `outcome` | A list of rules on a score, a metadata value, or the trace error. The first rule that matches sets the outcome. | `unknown` | 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](/agent-skills/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](/agent-skills/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. **`Python`** ```python Python 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, ) ``` **`TypeScript`** ```typescript TypeScript const mapping: Zep.TraceMapping = { taskFamily: { source: "fixed", value: "billing.support" }, objective: { source: "first_user_message" }, outcome: [ { rule: "score", name: "resolution", succeededAtOrAbove: 0.8, failedBelow: 0.4, }, ], scoreVerifier: true, }; const preview = await client.traceConnection.trace.get(connection.uuid!, { providerProjectId: projectId!, traceId: "trace-123", 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. **`Python`** ```python Python 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, ) ``` **`TypeScript`** ```typescript TypeScript const once = await client.agent.traceImport.create(agent.uuid!, { name: "Billing backfill", connectionUuid: connection.uuid, providerProjectId: projectId, selection: { traceIds: ["trace-123", "trace-456"] }, 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. **`Python`** ```python Python 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. ``` **`TypeScript`** ```typescript TypeScript const scheduled = await client.agent.traceImport.create(agent.uuid!, { name: "Billing production", connectionUuid: connection.uuid, providerProjectId: projectId, selection: { filter: { startedAfter: "2026-10-01T00:00:00Z", tagsAll: ["production"] } }, schedule: { intervalHours: 4, startFrom: "now", settleMinutes: 60, maxOpenHours: 24 }, 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](/agent-skills/learning-and-admission) 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](/agent-skills/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 | Operation | Use when | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `client.trace_connection.list` | You need to list the project's trace connections. | | `client.trace_connection.get` | You need the connection settings and credential hint. Zep does not return the credential. | | `client.trace_connection.update` | You need to change provider settings. Zep verifies changed settings before it stores them. | | `client.trace_connection.verify` | You need to check the credential and update the connection status. | | `client.trace_connection.delete` | You can delete a connection only when no active Trace import uses it. Zep keeps imported Traces. | | `client.agent.trace_import.list` and `client.agent.trace_import.get` | You need to list imports or read one. The response does not include a source cursor. | | `client.agent.trace_import.update` | You need to update an import with `expected_revision`. |