Skip to main content
Traces are an organizing component of a session. They are used to group completions together and provide a way to track the progress of a session. Named traces form the basis of Freeplay’s support for Agents.
Method NameParametersDescription
session.create_traceinput: str Input to the trace agent_name: str (optional) Name of the agent/trace. custom_metadata: dict[str, Unionscript Node npm install] (optional) Metadata to associate with the traceGenerate a TraceInfo object that will be used to group completions
trace.record_outputoutput: str, output of the agent/trace project_id: Id of the project to record to eval_results: dict[str, Unionypescript Nod] code evaluation results, optional test_run_info: TestRunInfo, optinalRecord the output to a trace
Traces are a more fine-grained way to group LLM interactions within a Session. A Trace can contain one or more completions and a Session can contain one or more Traces. Find a more detailed guide on how Sessions, Traces, and Completions fit together here. Traces are created off of an existing session object: 
input_question = "What color is the sky?"

# create or restore a session

session = fpClient.sessions.create()

# create the trace

trace_info = session.create_trace(
input=input_question, # Optional Parameters
agent_name="weather_agent",
custom_metadata={
"version": "1.0.8"
}
)
To tie a Completion to a given Trace you will pass the trace info in the record call 
from freeplay import Freeplay, RecordPayload, ResponseInfo, CallInfo, SessionInfo, TraceInfo

# create or restore a session

session = fpClient.sessions.create()

# create the trace

trace_info = session.create_trace(input=question)

# fetch prompt

# call LLM

# record with trace id

record_response = fpClient.recordings.create(
RecordPayload(
project_id=project_id,
all_messages=all_messages,
session_info=session_info,
inputs=input_variables,
prompt_version_info=formatted_prompt.prompt_info,
call_info=call_info,
response_info=response_info,
trace_info=trace_info, # Pass the trace info along
)
)
See a full code example here Once you have recorded completions to the trace and are on the final output, you must close your trace in order to wrap the completions together, you can also optionally record eval results to the trace at this point: 
# record output to the trace
output_answer = "blue" # from the LLM
trace_info.record_output(
  project_id=project_id,
  output=output_answer,
  eval_results={  # Optional trace eval logging
    "sentiment": 0.7,
    "valid_path": True,
  }
)

​
Updating a Trace

Trace information can also be updated, similar to a completion. This can be done by using the update_trace method. See the below example, note you must have the trace_id and the project_id to properly record: 
# Update the trace with feedback
# This uses update_trace to attach feedback to the entire trace
# of this interaction, including message ID reference
fpClient.customer_feedback.update_trace(
    project_id=project_id,
    trace_id=trace_info.trace_id,
    feedback={
      	'satisfaction': True,
        'relevance': 0.97,
        'message_id': 'abc82028639oksns'
    }
)