Setup

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

poetry add 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.

Method	Required	Description
`.prompt(user_prompt, system_prompt)`	Yes	The user input (and optional system prompt) to the agent
`.response(text)`	No	The final response from the agent
`.metadata(data, **kwargs)`	No	Custom key-value metadata for filtering
`.feedback(score, text)`	No	Submit user feedback for this run
`.status(code, message)`	No	Set a status code and message
`.error(status_message)`	No	Mark the run as failed
`.step(step_id)`	No	Create a step within the run
`.tool_call(tool_name, tool_call_id)`	No	Create a tool call within the run
`.end()`	Yes	End 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.

Method	Required	Description
`.prompt(text)`	Yes	The prompt sent to the LLM
`.response(text)`	Yes	The response returned by the LLM
`.model(requested, used)`	No	The model requested and actually used
`.tokens(prompt_uncached, prompt_cached, completion)`	No	Token counts for the step
`.cost(real_total)`	No	Cost of the step
`.finish_reason(reason)`	No	Finish reason from the LLM
`.tool_definitions(definitions)`	No	Tool definitions available to the LLM
`.status(code, message)`	No	Set a status code and message
`.error(status_message)`	No	Mark the step as failed
`.end()`	Yes	End 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.

Getting started

Supported frameworks

Custom Instrumentation

Monitoring

Integrations

Security

Set TCC environment variables

Install the SDK

Step 1: Install dependencies

Step 2: Create an agent run

Run methods

Step 3: Add steps to your run

Step methods

Maximize observability

​Set TCC environment variables

​Install the SDK

​Step 1: Install dependencies

​Step 2: Create an agent run

​Run methods

​Step 3: Add steps to your run

​Step methods

​Maximize observability

Set TCC environment variables

Install the SDK

Step 1: Install dependencies

Step 2: Create an agent run

Run methods

Step 3: Add steps to your run

Step methods

Maximize observability