Skip to main content
Agno instrumentation is available for Python only.

​
Set TCC environment variables

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

​
Instrument Agno

​
Step 1: Install dependencies

pip install "contextcompany[agno]"

​
Step 2: Add instrumentation

You’ll need to initialize instrumentation before Agno is imported. This is typically at the top of your application’s entry point (for example, in main.py or app.py).
main.py
import os
from dotenv import load_dotenv
load_dotenv()

# Import and initialize TCC instrumentation BEFORE importing Agno
from contextcompany.agno import instrument_agno

instrument_agno()

# Your existing Agno code
from agno.agent import Agent
from agno.models.openai import OpenAIChat

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[...],
    instructions=["You are a helpful assistant."],
)

response = agent.run("What is the weather in SF?")
That’s it! Your app will now be instrumented and any Agno agent runs, steps, and tool calls will be viewable in the dashboard.

​
Adding custom metadata

Custom metadata allows you to add additional properties to your agent runs. This is particularly useful for tying agent runs to your own specific business logic, letting you filter and analyze agent runs by user, organization, feature, or some other dimension. Agno uses OpenInference’s using_attributes context manager to attach metadata to spans:
main.py
from openinference.instrumentation import using_attributes

with using_attributes(
    metadata={
        # e.g. tag this agent run with a user id
        "userId": "4a6b111c-b53a-4d00-a877-67185022ab9e",
        "agentName": "weather-agent",
        "environment": "production",
    },
):
    response = agent.run("What is the weather in SF?")
Agent runs are automatically indexed by your custom metadata fields and can be filtered directly in the dashboard.
The tcc.* namespace is reserved. Only the reserved TCC metadata keys (tcc.runId, tcc.sessionId, tcc.conversational, tcc.agent, tcc.userId, tcc.userName, tcc.orgId, tcc.orgName) are recognized; any other tcc.* keys are ignored. None of them appear in your custom metadata.

​
Adding user feedback

User feedback allows you to collect score (thumbs up & thumbs down) and text feedback (up to 2000 characters) from end users on your agent runs. This is useful for tracking user satisfaction, identifying problematic responses, and filtering agent runs in the dashboard to focus on positive or negative feedback.

​
Step 1: Generate and pass a run ID

main.py
import uuid
from openinference.instrumentation import using_attributes

# Generate a unique run ID (must be a UUID) before your agent execution
run_id = str(uuid.uuid4())

with using_attributes(
    metadata={
        "tcc.runId": run_id,  # Pass the run ID in metadata
    },
):
    response = agent.run("What is the weather in SF?")

# Return the run_id to your client
return {"response": response, "run_id": run_id}

​
Step 2: Submit feedback from your client

Store the run_id on your client, then when the user provides feedback, submit it using the submit_feedback function. Both score and text are optional individually, but each request must include at least one of them: score is the thumbs rating. Use only "thumbs_up" or "thumbs_down". text is written feedback from your user, up to 2000 characters.
feedback.py
from contextcompany import submit_feedback

# Submit score and/or text feedback:
submit_feedback(
    run_id=run_id,  # The run ID from your agent execution
    score="thumbs_up",  # Optional thumbs rating: "thumbs_up" or "thumbs_down"
    text="This was a helpful response!",  # Optional written user feedback, up to 2000 characters
)
Agent runs with feedback can be filtered in the dashboard using the feedback filter.

​
Tracking agent sessions

Agent sessions represent multiple agent runs that are grouped together. The most common use case is tracking entire conversations between a human user and an AI agent in chatbot interfaces. Agent sessions can be tracked by setting session_id in the using_attributes context manager, or by using tcc.sessionId in metadata:
main.py
from openinference.instrumentation import using_attributes

session_id = "unique-session-identifier"

with using_attributes(
    session_id=session_id,
    metadata={
        "tcc.sessionId": session_id,  # Track agent sessions
    },
):
    response = agent.run("What is the weather in SF?")
The value of session_id should be a unique identifier for the agent session. This can be any string, but it’s generally recommended to use a UUID. Agent sessions are automatically indexed and can be filtered directly in the dashboard.

​
Marking runs as conversational

A conversational run is an agent run that was initiated by a user. Marking a run as conversational tells The Context Company that this run involves direct user interaction. This is important because conversational runs are the only runs monitored for user insights, such as user confusion, frustration, or any other custom insights you want to track. Runs that are not marked as conversational (e.g. background jobs, cron tasks, or internal automations) are excluded from user insight analysis. Mark a run as conversational by setting tcc.conversational to "true" in metadata:
main.py
from openinference.instrumentation import using_attributes

with using_attributes(
    metadata={
        "tcc.conversational": "true",
    },
):
    response = agent.run("What is the weather in SF?")

​
Identifying the agent

If your product ships more than one named agent, set the reserved tcc.agent metadata key to scope the run to a specific agent. The dashboard’s top-level agent selector, per-agent patterns and recaps, and the agent filter on the REST API and MCP tools all read from this key.
main.py
from openinference.instrumentation import using_attributes

with using_attributes(
    metadata={
        "tcc.agent": "support-agent",
    },
):
    response = agent.run("What is the weather in SF?")
Agent names that collide with reserved dashboard routes (for example runs, sessions, patterns, recaps, overview, search, failures, feedback, tools, topics, views, settings, mcp-and-api) are dropped.

​
Identifying users and organizations

Attach the end user and their organization to a run as first-class identity using the reserved tcc.userId, tcc.userName, tcc.orgId, and tcc.orgName metadata keys. This is not the same as adding a userId field to custom metadata — these keys promote user and org identity to dedicated dashboard filters and unlock native user/org search, per-user views, and per-org analytics. See User and organization identity for the full concept. Set these whenever you have a stable identifier for the end user or their organization in your product.
main.py
from openinference.instrumentation import using_attributes

with using_attributes(
    metadata={
        "tcc.userId": "user-123",
        "tcc.userName": "Jane Doe",
        "tcc.orgId": "org-456",
        "tcc.orgName": "Acme Inc.",
    },
):
    response = agent.run("What is the weather in SF?")
tcc.userName and tcc.orgName require the corresponding ID (tcc.userId / tcc.orgId) to also be set. Names without IDs are dropped.

​
Combining multiple options

You can combine all TCC options in a single using_attributes block:
main.py
import uuid
from openinference.instrumentation import using_attributes

run_id = str(uuid.uuid4())
session_id = "session-abc-123"

with using_attributes(
    session_id=session_id,
    metadata={
        # TCC-specific options
        "tcc.runId": run_id,
        "tcc.sessionId": session_id,
        "tcc.conversational": "true",
        "tcc.agent": "support-agent",
        "tcc.userId": "user-123",
        "tcc.userName": "Jane Doe",
        "tcc.orgId": "org-456",
        "tcc.orgName": "Acme Inc.",
        # Custom metadata (tracked automatically)
        "agentName": "weather-agent",
        "environment": "production",
    },
):
    response = agent.run("What is the weather in SF?")
KeyTypeDescription
tcc.sessionIdstringSession ID for grouping runs
tcc.conversationalstringSet to "true" if this run involves user interaction
tcc.runIdstringCustom run ID for feedback tracking
tcc.agentstringAgent name for first-class agent filtering
tcc.userIdstringEnd user’s ID. Required if setting tcc.userName.
tcc.userNamestringEnd user’s display name. Ignored unless tcc.userId is also set.
tcc.orgIdstringEnd user’s organization ID. Required if setting tcc.orgName.
tcc.orgNamestringOrganization display name. Ignored unless tcc.orgId is also set.
Other keysstringCustom metadata for filtering (tracked automatically)

​
Examples

See our examples repository for more detailed usage examples.