Python SDK reference (retrack-ai)
Reference for the retrack-ai Python connector: init, recall, feedback, flush, the Memory object, the explicit Retrack client and its exceptions.
Updated
The retrack-ai package is Retrack's open-source Python connector (MIT licence). It depends only on httpx and langchain-core, supports Python 3.10 and newer, and never raises into your agent's code.
pip install retrack-aiOne-line setup
retrack.init(agent, **options)
Records every LangGraph or LangChain agent run in the process from now on, with no callback to pass. Call it once where your agent starts; calling it again replaces the earlier setup.
| Argument | Default | Meaning |
|---|---|---|
agent | required | A name for this agent; memory is kept per agent |
api_key | RETRACK_API_KEY | Your project's key |
base_url | RETRACK_BASE_URL or https://api.retrack-ai.online | API address |
model_id | none | The model your agent uses; memory is matched to it |
tool_versions | {} | Versions of the APIs your tools call, such as {"stripe": "2026-09"} |
output_key | last AI message | The graph-state field that holds the final answer |
Only agent runs are recorded: a run that called a tool, or one that followed retrack.recall. A run an explicit rt.callback() already records is not recorded twice.
retrack.recall(task, **options) -> Memory
Memory for the task your agent is about to start. Links itself to the next run. Never raises; returns empty memory on any problem.
| Argument | Default |
|---|---|
max_playbooks | 3 (1 to 10) |
timeout | 1.5 seconds |
model_id, tool_versions | the values from init |
retrack.feedback(outcome, *, run_id=None, source="feedback", detail=None)
Reports how a run went. outcome is "success" or "failure"; source is "test", "event" or "feedback". Without run_id, it applies to the latest run. See Verifying runs.
retrack.flush(timeout=5.0) -> bool
Waits until recorded runs are sent. Useful at the end of short scripts and serverless handlers. Runs are also flushed when the process exits normally.
Memory
| Member | Meaning |
|---|---|
as_prompt() | Plain text for your agent's prompt: playbooks, then known failures. Empty string when there is nothing to add |
playbooks | List of playbook dictionaries: title, preconditions, steps (action, tool, optional when), pitfalls, score |
warnings | List of failure warnings: message, tool, error_class, recovery, unrecoverable and more |
holdout | True when this run is held out and gets no memory |
replay_plan | A plan to follow directly, only when plan replay is allowed |
protect(tools, max_same_failure=3) | Wraps LangChain tools with known fixes and a circuit breaker. See Known fixes |
bool(memory) | True when there is at least one playbook or warning |
Explicit client
Retrack(agent, **options)
The same options as init, for code that wants control over each run.
| Method | Meaning |
|---|---|
callback(task=None, output_key=None, replay_of=None) | A LangChain callback handler that records one run. task overrides the task text; replay_of is the playbook id when the run follows a replay plan |
recall(task, run_id=None, ...) | As retrack.recall; pass the run_id you give the graph to link them |
recall_node(task_key="task", into="retrack_memory") | A LangGraph node that recalls memory for state[task_key] into state[into] |
feedback(run_id, outcome=..., source="feedback", detail=None) | As retrack.feedback, for a given run |
flush(timeout=5.0), close(timeout=5.0) | Send pending runs; stop the background sender |
import uuid
from retrack import Retrack
rt = Retrack("support-agent", model_id="claude-haiku-5-5")
run_id = uuid.uuid4()
memory = rt.recall(task, run_id=run_id)
result = graph.invoke(
{"messages": [("system", memory.as_prompt()), ("user", task)]},
config={"callbacks": [rt.callback()], "run_id": run_id},
)
rt.feedback(run_id, outcome="success", source="event")Errors
| Exception | Raised by | Meaning |
|---|---|---|
retrack.recovery.KnownFailureError | protected tools | A known failure; the message includes the fix |
retrack.recovery.UnrecoverableToolError | protected tools | Retrying will not help; stop and handle it |
Nothing else in the connector raises into your code. Problems are logged on the retrack logger.
Environment variables
| Variable | Meaning |
|---|---|
RETRACK_API_KEY | Your project's key. Without it, capture and recall are off |
RETRACK_BASE_URL | API address, default https://api.retrack-ai.online |