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

bash

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

Python (LangChain)

bash

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.

spanora-setup

NPX Install

Tags

SKILL.md Content

Spanora Setup Agent Skill

1. When to Invoke

2. Public Documentation — Source of Truth

3. Prerequisites

4. Language Detection

5. Detection — Determine the Integration Pattern

JavaScript / TypeScript

Python

6. Package Manager Detection

JavaScript / TypeScript

Python

7. Install

JavaScript / TypeScript

Python (LangChain)

8. Integration — Read the Matching Reference

9. Ensure Full Instrumentation Coverage

10. Offer Optional Enrichments