instrument

AI Community

Skill notes

Step 1 — Scope

If $ARGUMENTS is provided, scope your work to those files or directories. Otherwise, discover the project root and instrument the main application code.

Step 2 — Detect Language & Frameworks

Scan the codebase to determine: Language: Python (look for *.py, pyproject.toml, requirements.txt) or TypeScript (look for *.ts, *.tsx, package.json) LLM frameworks in use — search imports for these patterns: Import pattern · Framework · Integration from openai / import OpenAI · OpenAI · track_openai

Step 3 — Identify the Call Graph

Find: Entrypoint: the top-level function that kicks off the agent (e.g., main, run, agent, handle_message, a route handler, or whatever the user's main orchestration function is) LLM call sites: functions that call an LLM provider directly Tool functions: retrieval, search, API calls, or other tool-like operations Existing config classes: dataclasses, Pydantic models, or plain classes holding model names, temperatures, prompts, or other tunable parameters

Entrypoint Parameter Rules

The function marked with entrypoint=True must only accept primitive-typed parameters: str, int, float, bool, and list/dict of primitives. This is because: Opik reads the function's type hints to build an input form in the UI Users will type these values manually in a text field via the Local Runner Complex types (Pydantic models, dataclasses, request objects, custom classes) cannot be entered in a UI input field

Step 4 — Add Framework Integrations

For each detected framework, add the appropriate integration at the module level. See the integration table above and references/integrations.md for the exact patterns. Python examples: TypeScript examples:

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
AI
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@tomevault-io · no license declared
Token usage
Moderate
Setup complexity
Manual integration
External API key
Required · Vendor-specific
Operating systems
macOS · Linux · Windows
Runtime requirements
Python
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
  • Env read
Network behavior
External requests
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Step 1 — Scope

If `$ARGUMENTS` is provided, scope your work to those files or directories. Otherwise, discover the project root and instrument the main application code.

02
Step 2 — Detect Language & Frameworks

Scan the codebase to determine: Language: Python (look for `*.py`, `pyproject.toml`, `requirements.txt`) or TypeScript (look for `*.ts`, `*.tsx`, `package.json`) LLM frameworks in use — search imports for these patterns: Import pattern · Framework · Integration `from openai` / `import OpenAI` · OpenAI · `track_openai`

03
Step 3 — Identify the Call Graph

Find: Entrypoint: the top-level function that kicks off the agent (e.g., `main`, `run`, `agent`, `handle_message`, a route handler, or whatever the user's main orchestration function is) LLM call sites: functions that call an LLM provider directly Tool functions: retrieval, search, API calls, or other tool-like operations Existing config classes: dataclasses, Pydantic models, or plain classes holding model names, temperatures, prompts, or other tunable parameters

04
Step 4 — Add Framework Integrations

For each detected framework, add the appropriate integration at the module level. See the integration table above and `references/integrations.md` for the exact patterns. Python examples: TypeScript examples:

05
Step 5 — Add @opik.track Decorators (Python) or Client Tracing (TypeScript)

Step 5 — Add @opik.track Decorators (Python) or Client Tracing (TypeScript)

06
Step 6 — Conversational Agents: Add threadid

If the agent handles multi-turn conversations (chat bots, support agents, multi-step assistants), wire `thread_id`: Skip this for single-shot agents or batch processing.

07
Step 7 — Environment Config

Follow the setup decision tree from the main opik skill: If the project has `.env` / `.env.local` → append `OPIK_API_KEY`, `OPIK_WORKSPACE`, `OPIK_URL_OVERRIDE` (if missing) If no `.env` exists → Python: create/update `~/.opik.config`; TypeScript: create `.env` or `.env.local` Never introduce a second config mechanism Never overwrite existing values

08
Step 8 — Install Dependencies

Print the install command but do NOT run it automatically. Let the user decide. Python: Plus any integration packages if needed (most are included in `opik`). TypeScript: Plus framework-specific packages: `opik-openai`, `opik-vercel`, `opik-langchain`, `opik-gemini` as needed.

09
Step 9 — Verify

After instrumentation, do a quick audit: [ ] Every LLM call site is traced (via integration wrapper or `@opik.track`) [ ] Exactly one function has `entrypoint=True` [ ] The entrypoint function accepts only primitive parameters (`str`, `int`, `float`, `bool`, `list`, `dict`) — no Pydantic models, dataclasses, or custom classes [ ] All `get_or_create_config()` calls and config field access happen inside `@opik.track`-decorated functions (or downstream from one)

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.