Installation

This guide covers installation and basic configuration of the Risicare SDK.

Requirements

Python

• Python: 3.10 or higher
• Operating System: Linux, macOS, or Windows
• Network: Outbound HTTPS to ingest.risicare.ai (spans) and api.risicare.ai (scores)

JavaScript/TypeScript

• Node.js: 18.0.0 or higher
• Operating System: Linux, macOS, or Windows
• Network: Outbound HTTPS to ingest.risicare.ai (spans) and api.risicare.ai (scores)

Install the SDK

Framework Extras (Python)

Install with framework-specific extras:

# LangChain
pip install 'risicare[langchain]'
 
# LangGraph
pip install 'risicare[langgraph]'
 
# LlamaIndex
pip install 'risicare[llamaindex]'
 
# CrewAI
pip install 'risicare[crewai]'
 
# AutoGen
pip install 'risicare[autogen]'
 
# OpenAI Agents SDK
pip install 'risicare[openai-agents]'
 
# DSPy
pip install 'risicare[dspy]'
 
# Instructor
pip install 'risicare[instructor]'
 
# LiteLLM
pip install 'risicare[litellm]'
 
# Pydantic AI
pip install 'risicare[pydantic-ai]'
 
# All frameworks
pip install 'risicare[frameworks]'
 
# All frameworks + all providers + OpenTelemetry
pip install 'risicare[all]'

Provider Extras (Python)

Install with provider-specific extras to pull in the correct dependency versions:

# Amazon Bedrock
pip install 'risicare[bedrock]'
 
# Google Vertex AI
pip install 'risicare[vertexai]'
 
# Groq
pip install 'risicare[groq]'
 
# Ollama
pip install 'risicare[ollama]'
 
# Together AI
pip install 'risicare[together]'
 
# Cerebras
pip install 'risicare[cerebras]'
 
# HuggingFace
pip install 'risicare[huggingface]'
 
# All providers
pip install 'risicare[providers]'

OpenTelemetry Extra (Python)

Bridge Risicare spans to an OpenTelemetry-compatible backend:

pip install 'risicare[otel]'

This installs opentelemetry-sdk and opentelemetry-api (>= 1.20.0). Enable the bridge with otel_bridge=True in risicare.init().

Meta Extras (Python)

Combine multiple extras with a single install:

# Everything
pip install 'risicare[all]'

Get an API Key

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). Access is by invitation — there is no self-serve sign-up
2. The first person to sign in to a new organization gets a default project and API key on that first sign-in. The key is shown once, on the dashboard home page — copy it before you leave that page
3. Joined an organization that already has a project, or missed that key? Go to Settings → API Keys → Create API Key and copy the key from the dialog (also shown only once; owners and admins can create keys). Settings lists existing keys by prefix only; it cannot show a key again. Creating a key needs a sign-in from the last 15 minutes — if you are asked to re-authenticate, do so and create the key again
4. Need more projects? Owners and admins can click the project dropdown → New Project — each project gets its own key, shown once in the Project Created dialog. Creating a project needs a sign-in from the last 15 minutes; if Create Project does nothing, sign out, sign in again and retry

Configuration

Environment Variables

The simplest configuration uses environment variables:

# Required
export RISICARE_API_KEY=rsk-your-api-key
 
# Optional
export RISICARE_TRACING=true              # Enable tracing
export RISICARE_ENVIRONMENT=production    # Environment name
export RISICARE_SERVICE_NAME=my-agent     # Service name for filtering
export RISICARE_SERVICE_VERSION=1.0.0     # Service version
export RISICARE_SAMPLE_RATE=1.0           # Sampling rate (0.0-1.0)
export RISICARE_TRACE_CONTENT=true        # Capture prompt/completion text

Programmatic Configuration

For more control, initialize explicitly:

Configuration Precedence

Configuration is resolved in this order (later overrides earlier):

1. Default values
2. Environment variables
3. risicare.init() arguments

Verify Installation

Test that the SDK is working:

import risicare
 
# Initialize
risicare.init()
 
# Create a test trace
tracer = risicare.get_tracer()
span = tracer.start_span("test-span")
span.set_attribute("test", True)
span.end()
print("Risicare is working!")
 
# Ensure spans are exported
risicare.shutdown()

Check the dashboard to see your test span.

Framework Integrations

Frameworks are auto-instrumented when risicare.init() is called. Just install the framework package alongside Risicare:

# LangChain / LangGraph
pip install risicare langchain langgraph
 
# CrewAI
pip install risicare crewai
 
# AutoGen
pip install risicare autogen-agentchat

No separate integration packages are needed — risicare.init() detects installed frameworks automatically via import hooks.

Troubleshooting

No traces appearing

1. Confirm your entrypoint actually does import risicare — environment variables alone install no instrumentation, and a process that never imports the SDK emits zero spans with no error. When the Python SDK starts with an API key and with debug off, it prints [risicare] Tracing active — endpoint: ..., service: .... This line shows that the SDK started. It does not show that spans arrive. The JavaScript SDK prints no startup line.
2. Verify your API key is set correctly. With no key the SDK sends nothing, init() logs one WARNING that says so, and flush() returns False
3. Check RISICARE_TRACING=true is set
4. Check for network connectivity to ingest.risicare.ai
5. Spans are flushed by an atexit hook on normal exit. If your process is killed with SIGKILL or exits via os._exit(), call risicare.shutdown() explicitly to flush.

If your process forks — gunicorn, uvicorn workers, celery --prefork — or if traces stopped arriving after an outage, see Production & Failure Modes.

Import errors

Make sure you have the correct Python version:

python --version  # Should be 3.10+

Debug mode

A failed span export logs a WARNING that names the HTTP status. To see each attempt and what else the SDK is doing, raise the SDK's logger:

import logging
 
logging.getLogger("risicare").setLevel(logging.DEBUG)

Use debug=True only when you actually want spans echoed to the console, on non-production data.

IDE Integration

Next Steps