Concepts

​

Runs

A run is a single end-to-end execution of your agent - from the initial prompt to the final response. A run can include multiple LLM calls, tool invocations, and reasoning steps. Every run is analyzed for silent failures. Each run is assigned a UUID automatically. To provide your own (for example, to tie user feedback to a run from your client), set tcc.runId in the run’s metadata.

​

Steps

A step is a single LLM request and its response within a run. An agent run typically involves multiple steps as the model reasons, calls tools, and refines its answer. Steps help you pinpoint exactly where in the reasoning chain something went wrong.

​

Tool calls

A tool call is a single invocation of a tool function - the name, the arguments passed, the result returned, and whether it succeeded or failed. When grouped under a step, it means the LLM triggered that tool as part of its reasoning.

​

Sessions

A session groups multiple runs together, typically representing a full conversation between a user and your agent. Sessions let you see the complete user journey across multiple back-and-forth interactions. Group runs into a session by setting tcc.sessionId in the run’s metadata.

​

Conversational runs

By default, runs are treated as background executions (cron jobs, internal automations, etc.). Marking a run as conversational tells the platform that a real user is interacting with the agent. Only conversational runs are analyzed for user insights like frustration, confusion, and custom patterns. Mark a run as conversational by setting tcc.conversational to true in the run’s metadata.

​

Agents

An agent is a named workflow or assistant in your product — for example support-agent, onboarding-bot, or code-reviewer. Most teams ship more than one agent from the same codebase, and a single user might interact with several of them. Attach a run to an agent by setting tcc.agent to the agent’s name in the run’s metadata. The platform promotes this to a first-class dimension:

• Agent selector. A top-level selector lets you scope the entire dashboard — runs, sessions, patterns, recaps, insight search — to a single agent or view everything together.
• Per-agent patterns and recaps. Patterns and recaps can be configured to target specific agents, so behavioral signals and weekly summaries stay scoped to the agent that produced them.
• Native agent filter. agent is a first-class filter on the REST API and MCP tools, separate from custom metadata.

Set tcc.agent whenever a run belongs to a distinct agent in your product. Runs without tcc.agent are grouped under a default unscoped view.

​

User and organization identity

The Context Company treats the end user of your agent (and the organization / workspace / tenant they belong to in your product) as first-class entities — not just another piece of custom metadata. Attach them to a run by setting these reserved metadata keys:

• tcc.userId — the stable ID of the end user in your system
• tcc.userName — their display name (optional, requires tcc.userId)
• tcc.orgId — the ID of their organization / workspace / tenant in your system
• tcc.orgName — the organization’s display name (optional, requires tcc.orgId)

Why use these instead of generic custom metadata like userId or customer_id?

• Dedicated dashboard filters. Users and orgs get their own first-class filters in the dashboard, separate from custom metadata.
• Native user and org search. Look up any user or org by ID or name from anywhere in the product to jump straight to their runs, sessions, and patterns.
• Per-user and per-org analytics. Unlock user-level views, cohort analysis, and per-org breakdowns of patterns, frustration, and confusion.
• Stable identity across runs and sessions. The same tcc.userId ties every run, session, and piece of feedback for that user together.

Set them whenever you have a stable identifier for the end user or their organization. If you only set a name without the corresponding ID, the name is dropped. Each framework page shows the exact syntax for setting these on a run, and some SDK wrappers expose them as typed parameters.

​

TCC metadata keys

The reserved keys below are the universal contract for controlling runs and attaching first-class user and organization identity. Each framework’s page shows the exact syntax for setting them, and some SDK wrappers expose them as typed parameters that set these keys for you. The entire tcc.* namespace is reserved. Any keys outside the ones above are ignored, and none of them are stored as custom metadata on the run.

​

Silent failures

Traditional monitoring catches errors that throw exceptions. Silent failures are the ones that don’t - the agent returns a 200 but the response is wrong:

• Bad tool calls - wrong arguments, wrong timing, or unnecessary invocations
• Hallucinations - fabricated information presented as fact
• Infinite loops - repeated identical calls burning tokens
• User confusion - responses that don’t address what the user actually asked

The platform detects these automatically across all your conversational runs.