Skip to main content

​
Instrumentation Quickstart

This quickstart guide walks you through instrumenting your first AI agent with Cascade’s observability platform. You’ll set up automatic tracing for an Anthropic Claude agent and view detailed execution data in the Cascade Dashboard, including prompts, completions, token usage, costs, and latency metrics.

​
Get your model provider API key

Obtain an API key from your preferred model provider. Examples: You’ll use this key to authenticate requests made by your model client. Cascade does not replace or proxy your model provider.

​
Get your Cascade API key

Go to the Cascade Dashboard to access your project.
  1. Enter the API key we provided to you (format: cascade_xxx_xxx)
  2. Your traces will be automatically isolated to your project
Contact us to get your Cascade API key. Each key is mapped to your specific project for secure multi-tenant isolation.

​
Set up your environment

Create a .env file in your project directory to store your API keys securely.
.env
ANTHROPIC_API_KEY=sk-ant-your-key-here
CASCADE_API_KEY=cascade_your_key_here
Never commit your .env file to version control. Add it to your .gitignore file.

​
Install Cascade SDK

Install the required packages using pip. 
pip install cascade-sdk anthropic python-dotenv

​
Instrument your first traced agent

Create a file called my_agent.py with the following code.
my_agent.py
import os
from dotenv import load_dotenv
from cascade import init_tracing, trace_run, wrap_llm_client
from anthropic import Anthropic

# Load environment variables
load_dotenv()

# Initialize tracing with your project name
init_tracing(
    project="my_first_agent",
    api_key=os.getenv("CASCADE_API_KEY")
)

# Wrap your Anthropic client (all calls are now automatically tracked!)
client = wrap_llm_client(Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY")))

# Create a traced agent run
with trace_run("SimpleAgent", metadata={"task": "greeting"}):
    response = client.messages.create(
        model="claude-3-5-haiku-20241022",
        max_tokens=100,
        messages=[
            {"role": "user", "content": "Say hello and introduce yourself in one sentence."}
        ]
    )
    
    print(response.content[0].text)

print("\n 🚀 Trace sent! Check your dashboard to see the results.")
The wrap_llm_client() function automatically captures all LLM interactions with zero additional code changes.

​
Run your agent

Execute your agent script from the terminal. 
python my_agent.py
You should see output similar to this: 
Hello! I'm Claude, an AI assistant created by Anthropic to be helpful, harmless, and honest.

🚀 Trace sent! Check your dashboard to see the results.

​
View your trace in the dashboard

Open the Cascade Dashboard to analyze your agent’s execution.
  1. Enter your Cascade API key if prompted
  2. Find your trace in the list with the name SimpleAgent
  3. Click on the trace to view detailed information

​
What gets tracked automatically

When you wrap your LLM client with wrap_llm_client(), Cascade automatically captures comprehensive telemetry without requiring additional instrumentation:
  • Full prompts: Complete user messages and system prompts
  • Completions: Full responses from the LLM
  • Token usage: Input tokens, output tokens, and total tokens
  • Cost estimation: Calculated based on current model pricing
  • Latency: Response time in milliseconds
  • Metadata: Model name, provider, and parameters
  • Errors: Exception details and stack traces if failures occur
The minimal setup shown here is production-ready. The wrap_llm_client() function handles all tracing automatically, you only need to wrap your client once.