Skip to main content

​
Using Traces

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. For a comprehensive guide on building agents with traces, see Agents.
Method NameParametersDescription
session.create_traceinput: str - Input to the trace. agent_name: str (optional) - Name of the agent/trace. parent_id: UUID (optional) - Parent trace or completion ID for nesting. kind: str (optional) - Either 'tool' or 'agent'. name: str (optional) - Name of the trace/tool. custom_metadata: dict[str, Any] (optional) - Metadata to associate with the trace.Generate a TraceInfo object that will be used to group completions
trace.record_outputoutput: str - Output of the agent/trace. project_id: str - ID of the project to record to. eval_results: dict[str, Any] (optional) - Code evaluation results. test_run_info: TestRunInfo (optional)Record 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. For a complete code example, see Record Traces. Traces are created off of an existing session object: 
input_question = "What color is the sky?"

# create or restore a session
session = fp_client.sessions.create()

# create the trace
trace_info = session.create_trace(
  input=input_question,
  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, 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,
trace_info=trace_info  # Pass the trace info along
)
)
For a complete working example, see Record Traces. For agent-specific patterns, see Agents. 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,
  }
)

​
Adding Tools to Traces

When building agents that use tools, tool calls are recorded as the output of an LLM call by default. You can also add explicit tool spans to provide more data about tool execution, including latency and other metadata. These are recorded as a Trace with kind='tool' and linked to the parent completion using parent_id. For complete examples and code snippets, see Tool Calls.

​
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'
    }
)