spanora-setup（斯帕诺拉设置）

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:

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.

1. 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.
2. If already set, proceed to the next step.
3. 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.

1. 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:

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:

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:

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

Python

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:

1. Auto-telemetry — experimental_telemetry for Vercel AI SDK, auto-instrumentation for LangChain. Preferred when available — zero manual work.
2. Provider wrappers — trackOpenAI, trackAnthropic, trackVercelAI / trackVercelAIStream. Use when auto-telemetry is unavailable for a call site (e.g. tool-loop agents, custom agent patterns).
3. 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.