Skip to main content

​
Set TCC environment variables

Our SDKs default to using the TCC_API_KEY environment variable.
.env
TCC_API_KEY="your-api-key"

​
Install the SDK

​
Step 1: Install dependencies

pip install contextcompany

​
Step 2: Create an agent run

An agent run represents a single execution of your agent, from the moment it receives a user input to the final response. Create a run before your agent loop begins, and end it after your agent loop completes. Initialize a run with tcc.run(). A run requires a prompt before calling .end(). The response is optional. Calling .end() will export the finalized run with all its parameters.
main.py
import contextcompany as tcc

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

# --- Your agent loop ---
# ...
# --- End of agent loop ---

r.response("The weather in London is 15°C and cloudy.")  # optional
r.end()  # required
That’s it! Your agent run will now be tracked and viewable in the dashboard.

​
Run methods

The following methods are available on a run. See Run Usage for more details.
MethodRequiredDescription
.prompt(user_prompt, system_prompt)YesThe user input (and optional system prompt) to the agent
.response(text)NoThe final response from the agent
.metadata(data, **kwargs)NoCustom key-value metadata for filtering
.feedback(score, text)NoSubmit user feedback for this run
.status(code, message)NoSet a status code and message
.error(status_message)NoMark the run as failed
.step(step_id)NoCreate a step within the run
.tool_call(tool_name, tool_call_id)NoCreate a tool call within the run
.end()YesEnd the run and export it

​
Step 3: Add steps to your run

Steps represent individual LLM calls within an agent run. Use them to track the reasoning flow of your agent. A step requires both a prompt and a response before calling .end().
main.py
import contextcompany as tcc

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

# --- Your agent loop ---
s = r.step()
s.prompt("You are a weather agent. The user asked: What is the weather in London?")  # required
s.response("The weather in London is 15°C and cloudy.")  # required
s.model(requested="gpt-4", used="gpt-4-0613")
s.end()
# --- End of agent loop ---

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

​
Step methods

The following methods are available on a step. See Step Usage for more details.
MethodRequiredDescription
.prompt(text)YesThe prompt sent to the LLM
.response(text)YesThe response returned by the LLM
.model(requested, used)NoThe model requested and actually used
.tokens(prompt_uncached, prompt_cached, completion)NoToken counts for the step
.cost(real_total)NoCost of the step
.finish_reason(reason)NoFinish reason from the LLM
.tool_definitions(definitions)NoTool definitions available to the LLM
.status(code, message)NoSet a status code and message
.error(status_message)NoMark the step as failed
.end()YesEnd the step and export it

​
Maximize observability

Once instrumented, you can enrich your data with additional context:
  • Optional run data: response and error handling
  • Optional step data: model, token usage, cost, finish reason, tool definitions, and error handling
  • Custom metadata: tie agent runs to your business logic (user, organization, feature, etc.)
  • User feedback: collect thumbs up/down scores and text feedback from end users
  • Agent sessions: group related runs into sessions to track full conversations
  • Debug mode: log payloads as they are created and sent
See the Run Usage, Step Usage, and Tool Call Usage guides for detailed examples.