Quickstart

Get Risicare running in your project in under 5 minutes: sign in, get an API key, install the SDK, and send your first trace.

Prerequisites

Python:

• Python 3.10 or higher
• An AI agent using OpenAI, Anthropic, or another supported provider

JavaScript/TypeScript:

• Node.js 18.0.0 or higher
• An AI agent using any of the 12 supported providers (OpenAI, Anthropic, Google, Mistral, Groq, Cohere, Together, Ollama, HuggingFace, Cerebras, Bedrock, Vercel AI)

Get an API key (takes 1 minute):

1. Sign in at app.risicare.ai with GitHub, using the GitHub account whose email matches your invitation — the public email on your GitHub profile if you have set one, otherwise your primary email
2. The first person to sign in to a new organization gets a default project and API key, created on that first sign-in. The key is shown once, on the dashboard home page — click Copy and store it before you leave that page
3. Everyone else — you joined an organization that already has a project, or you missed the key on your home page: go to Settings → API Keys, click Create API Key, and copy the key from the dialog. It is also shown only once. Owners and admins can create keys; members and viewers cannot — ask an owner or admin to create a key for you. (Creating a key needs a recent sign-in — if you are asked to re-authenticate, sign in again and retry.)

Paste the key exactly as the dashboard shows it. Do not check its format in your code.

Installation

Check that your key works (Python, optional)

Before instrumenting an agent, confirm the key with a short script. It sends one trace and needs no LLM provider:

export RISICARE_API_KEY=rsk-your-api-key

import risicare
 
risicare.init()  # reads RISICARE_API_KEY from the environment
 
@risicare.trace
def hello():
    return "hello from risicare"
 
hello()
risicare.shutdown()  # sends the trace before the script exits

A trace named hello then appears on the Traces page of the project the key belongs to, usually within seconds. To check from code, call risicare.flush() one time at the end of the run: True means that the gateway accepted every span and score. When it is False, read risicare.get_metrics() (dropped_spans_by_reason, rejected_spans, failed_scores). An acknowledgement means that the span is queued, not that it is stored. With no API key the SDK sends nothing: init() logs one WARNING that says so, and flush() returns False.

The script exits normally even when the key is refused, so read what it prints. A line beginning Risicare: spans are NOT reaching means the trace was not delivered. It names the HTTP status: it answered HTTP 401 means that the key is invalid or was not copied in full. Keys are shown only once, so if you did not save yours, create a new one. If that line does not appear but the trace is still missing, check that the project selector shows the project the key belongs to.

Tier 0: One Import, No Configuration

The fastest way to start: set two environment variables and add a single import at the top of your entrypoint. You configure nothing, and you do not change your agent logic.

export RISICARE_API_KEY=rsk-your-api-key
export RISICARE_TRACING=true

import risicare  # the one line you add — this installs the import hooks
 
from openai import OpenAI
 
client = OpenAI()
# ... your existing agent code, unchanged ...

python your_agent.py

Every OpenAI call made after that import is traced automatically.

What You'll See

After running your agent, open the Risicare Dashboard. Traces usually appear within seconds. They can take longer when the platform is under load.

Each trace shows:

• Complete execution flow — Every LLM call, tool use, and decision point
• Token usage & cost — Automatic conversion to USD per model (OpenAI, Anthropic, etc.)
• Prompts & completions — off by default. Set RISICARE_TRACE_CONTENT=true (or trace_content=True) to capture request/response text
• Timing breakdown — Latency per span, total trace duration
• Error detection — Failed calls are automatically flagged and classified

Tier 1: Explicit Configuration

For more control—and to group related LLM calls into a single trace—use risicare.init() with @trace:

Error Handling

Errors inside traced functions are automatically captured with full exception details:

import risicare
from risicare import trace
 
risicare.init(api_key="rsk-your-api-key")
 
from openai import OpenAI
client = OpenAI()
 
@trace
def risky_operation(query: str):
    # An exception raised here is recorded on the trace, then re-raised to you
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": query}],
    )
    return response.choices[0].message.content
 
try:
    risky_operation("What is quantum computing?")
finally:
    risicare.shutdown()  # once, when the program is done — flushes spans even after a failure

from risicare import report_error
 
try:
    result = tool.execute()
except ToolError as e:
    report_error(e)      # Records the error and classifies it against the taxonomy
    result = fallback()  # Handle gracefully

Tier 2: Agent Identity

Add agent identity to your code:

View Your Traces

Open the Risicare Dashboard to see:

• Traces: Complete execution flows with timing
• Spans: Individual LLM calls — with prompts and completions when content capture is on
• Costs: Token usage and cost breakdown by model
• Errors: Automatic error detection and classification

Next Steps