Skip to main content
A step represents a single request to an LLM and its response within an agent run. A step requires both a prompt and a response before calling .end(). All setter methods return self, so you can chain calls: 
s.prompt("Hello").response("World").model(requested="gpt-4", used="gpt-4-0613").end()

​
Required

​
Create step

There are two ways to create a step: 
s = r.step()

s = tcc.step(run_id=r.run_id)
ParameterRequiredDescription
step_idNoCustom step ID. If not provided, a UUID is automatically generated.
import contextcompany as tcc

r = tcc.run()

# Option 1: Create a step from a run
s = r.step()

# Option 2: Create a step directly with a run ID
s = tcc.step(run_id=r.run_id)

​
Set prompt

The prompt is required before calling .end(). 
s.prompt(text)
ParameterRequiredDescription
textYesThe prompt sent to the LLM
s.prompt("You are a weather agent. The user asked: What is the weather in London?")

​
Set response

The response is required before calling .end(). 
s.response(text)
ParameterRequiredDescription
textYesThe response returned by the LLM
s.response("The weather in London is 15°C and cloudy.")

​
End step

End the step and export it. A step must have both a prompt and a response set before calling .end(). The step cannot be modified after calling .end(). 
s = r.step()
s.prompt("You are a weather agent. The user asked: What is the weather in London?")

# --- Your LLM call ---
# ...
# --- End of LLM call ---

s.response("The weather in London is 15°C and cloudy.")
s.end()

​
Optional step data

​
Tracking costs

Costs are calculated automatically based on the model and token usage you provide, or you can set the cost directly with your own value.

​
Set model

Track which model was requested and which was actually used. 
s.model(requested, used)
ParameterRequiredDescription
requestedNoThe model that was requested
usedNoThe model that was actually used
s.model(requested="gpt-4", used="gpt-4-0613")

​
Set token usage

Track token counts for the step. 
s.tokens(prompt_uncached, prompt_cached, completion)
ParameterRequiredDescription
prompt_uncachedNoNumber of uncached prompt tokens
prompt_cachedNoNumber of cached prompt tokens
completionNoNumber of completion tokens
s.tokens(
    prompt_uncached=150,
    prompt_cached=50,
    completion=25,
)

​
Set cost

Alternatively, set the cost directly. 
s.cost(real_total)
ParameterRequiredDescription
real_totalYesThe total cost of the step
s.cost(real_total=0.0035)

​
Set finish reason

Set the finish reason returned by the LLM. 
s.finish_reason(reason)
ParameterRequiredDescription
reasonYesThe finish reason returned by the LLM (e.g. "stop", "tool_call")
s.finish_reason("stop")

​
Set tool definitions

Set the tool definitions available to the LLM for this step. 
s.tool_definitions(definitions)
ParameterRequiredDescription
definitionsYesThe tool definitions available to the LLM for this step
s.tool_definitions('[{"name": "get_weather", "description": "Get the weather for a location"}]')

​
Mark step as failed

Sets the status code to error and exports the payload. The step cannot be modified after calling .error(). Unlike .end(), calling .error() does not require a prompt or response to be set. 
s.error(status_message)
ParameterRequiredDescription
status_messageNoA description of the error
import contextcompany as tcc

r = tcc.run()
r.prompt("What is the weather in London?")

s = r.step()
s.prompt("Calling weather API...")

try:
    result = call_weather_api()
    s.response(result)
    s.end()
except Exception as e:
    s.error(status_message=str(e))

# Run still ends successfully even if a step fails
r.end()