Documentation menu

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-ai

One-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.

ArgumentDefaultMeaning
agentrequiredA name for this agent; memory is kept per agent
api_keyRETRACK_API_KEYYour project's key
base_urlRETRACK_BASE_URL or https://api.retrack-ai.onlineAPI address
model_idnoneThe model your agent uses; memory is matched to it
tool_versions{}Versions of the APIs your tools call, such as {"stripe": "2026-09"}
output_keylast AI messageThe 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.

ArgumentDefault
max_playbooks3 (1 to 10)
timeout1.5 seconds
model_id, tool_versionsthe 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

MemberMeaning
as_prompt()Plain text for your agent's prompt: playbooks, then known failures. Empty string when there is nothing to add
playbooksList of playbook dictionaries: title, preconditions, steps (action, tool, optional when), pitfalls, score
warningsList of failure warnings: message, tool, error_class, recovery, unrecoverable and more
holdoutTrue when this run is held out and gets no memory
replay_planA 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.

MethodMeaning
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

ExceptionRaised byMeaning
retrack.recovery.KnownFailureErrorprotected toolsA known failure; the message includes the fix
retrack.recovery.UnrecoverableToolErrorprotected toolsRetrying 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

VariableMeaning
RETRACK_API_KEYYour project's key. Without it, capture and recall are off
RETRACK_BASE_URLAPI address, default https://api.retrack-ai.online