Spanora Setup Agent Skill You are integrating Spanora AI observability into the user's project. Follow this guide step by step. 1. When to Invoke Activate this skill when the user says any of: "add spanora", "setup spanora", "integrate spanora" "add AI observability", "add LLM monitoring" "monitor LLM calls with spanora", "track AI costs" "instrument my agent", "add tracing to my agent" mentions "spanora" in the context of adding observability 2. Public Documentation — Source of Truth The official Spanora documentation at https://spanora.ai/docs is always up to date and is the canonical source of truth. The bundled references/ files in this skill are the primary step-by-step guide, but if you encounter ambiguity, an unfamiliar API, edge cases, or something that doesn't match what you see in the user's code — fetch the relevant doc page using WebFetch. If the public docs contradict a bundled reference, the public docs win. Key pages by integration pattern: Pattern Doc page Vercel AI SDK https://spanora.ai/docs/integrations/vercel-ai OpenAI SDK https://spanora.ai/docs/integrations/openai Anthropic SDK https://spanora.ai/docs/integrations/anthropic LangChain Python https://spanora.ai/docs/integrations/langchain Raw OTEL / other https://spanora.ai/docs/integrations/raw-otel TypeScript SDK reference https://spanora.ai/docs/sdk OTEL attribute conventions https://spanora.ai/docs/sdk/attributes You do not need to fetch docs on every run — only when something is unclear or you suspect the bundled references may be stale. 3. Prerequisites The user must have a Spanora API key (starts with ak_ ). Never ask the user to paste their API key into the conversation. Check if SPANORA_API_KEY is already set in .env (or .env.local ) or as a shell environment variable. Only check for presence — do not output or log the value. If already set, proceed to the next step. If not set, instruct the user to add it themselves: Tell them: "Please add your Spanora API key to your .env file as SPANORA_API_KEY=ak_... . You can find your key at https://spanora.ai/settings ." Do not accept the key in conversation or write the key value to any file. Wait for the user to confirm they have set it before proceeding. If .env is not in .gitignore , remind the user to add it. 4. Language Detection Determine the project language by checking for config files in the project root: File found Language package.json JavaScript / TypeScript pyproject.toml Python setup.py Python requirements.txt Python If both JS and Python files are present, ask the user which part of the project to instrument. 5. Detection — Determine the Integration Pattern JavaScript / TypeScript Read package.json and check dependencies and devDependencies : Dependency found Pattern to use ai Pattern A — Vercel AI SDK @anthropic-ai/sdk Pattern B — Anthropic SDK openai Pattern C — OpenAI SDK None of the above Pattern D — Raw Core SDK If multiple are present, prefer in order: A > B > C. Use the pattern matching the SDK the user's code actually calls. If unsure, ask. Python Read pyproject.toml (or requirements.txt / setup.py ) and check dependencies: Dependency found Pattern to use langchain Pattern E — LangChain / LangGraph More Python patterns may be added in the future. If the user's Python project does not use LangChain, inform them that Spanora supports any Python framework via raw OpenTelemetry — refer them to the LangChain reference as a template for OTEL setup. 6. Package Manager Detection JavaScript / TypeScript File found Package manager pnpm-lock.yaml pnpm yarn.lock yarn bun.lockb bun package-lock.json npm Python File found Package manager uv.lock uv poetry.lock poetry Pipfile.lock pipenv Otherwise pip 7. Install JavaScript / TypeScript pnpm add @spanora-ai/sdk

or: npm install @spanora-ai/sdk / yarn add @spanora-ai/sdk / bun add @spanora-ai/sdk

Python (LangChain) pip install opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-langchain langgraph

or: uv add ... / poetry add ... / pipenv install ...

No Spanora SDK is needed for Python — tracing uses standard OpenTelemetry. 8. Integration — Read the Matching Reference Based on the detected pattern, read the corresponding reference file for code examples and API usage: JavaScript / TypeScript: Pattern A (Vercel AI SDK): Read references/vercel-ai.md Pattern B (Anthropic SDK): Read references/anthropic.md Pattern C (OpenAI SDK): Read references/openai.md Pattern D (Raw Core SDK): Read references/core-sdk.md Python: Pattern E (LangChain / LangGraph): Read references/langchain-python.md For JS/TS patterns, always also read references/common.md for shared patterns: init() , shutdown() , tool tracking ( trackToolHandler , runTool ), multi-agent shared context, agent naming guidance, API key setup, and the migration checklist. Python patterns are self-contained in their reference file. Apply the patterns from the reference files to the user's code. The reference files contain production-ready examples verified against the SDK source and integration tests. 9. Ensure Full Instrumentation Coverage Every AI execution must produce at least one trace. For each LLM call site in the user's code, use the highest-fidelity approach available: Auto-telemetry — experimental_telemetry for Vercel AI SDK, auto-instrumentation for LangChain. Preferred when available — zero manual work. Provider wrappers — trackOpenAI , trackAnthropic , trackVercelAI / trackVercelAIStream . Use when auto-telemetry is unavailable for a call site (e.g. tool-loop agents, custom agent patterns). Core SDK functions — trackLlm , trackLlmStream , recordLlm . Fallback for any LLM call not covered by the above. After applying the base integration, scan the user's code for any LLM call that would not produce a span. If found, wrap it with the appropriate tracking function from the list above. Do not leave blind spots. 10. Offer Optional Enrichments After applying the base integration, mention these optional features to the user. Do not add them by default — only include them if the user's code has the relevant context available or the user asks for them: User & org context — userId , orgId , agentSessionId on track() calls. Links traces to end users, tenants, and sessions in the dashboard. Only add if the code has access to these values (e.g. from a request context, auth session, or API input). Operation type — operation on LLM meta ( trackLlm , trackOpenAI , trackAnthropic , recordLlm ). Defaults to "chat" . Set to "embeddings" for embedding calls or "text_completion" for completion calls. Only relevant when the user's code makes non-chat LLM calls. Field name reference: track() uses agent (not agentName ) for the agent name LLM tracking functions use prompt (not promptInput ) for the input prompt LLM result/extractors use output (not promptOutput ) for the output text Each reference file has an "Optional Enrichments" section with code examples for these features.