[OPIK-5031][DOCS]: initial PY and TS docs for blueprints;#6101
[OPIK-5031][DOCS]: initial PY and TS docs for blueprints;#6101
Conversation
github-actions
Bot
added
the
documentation
📋 PR Linter Failed❌ Incomplete Issues Section. You must reference at least one GitHub issue ( |
|
🌿 Preview your docs: https://opik-preview-0dbfe684-12ab-43fa-b32d-e726e2753a23.docs.buildwithfern.com/docs/opik The following broken links were found: Page: https://opik-preview-0dbfe684-12ab-43fa-b32d-e726e2753a23.docs.buildwithfern.com/docs/opik/integrations/harbor Page: https://opik-preview-0dbfe684-12ab-43fa-b32d-e726e2753a23.docs.buildwithfern.com/docs/opik/integrations/harbor/ 📌 Results for commit 6f46b19 |
![baz-reviewer[bot]](https://avatars.githubusercontent.com/in/933528?s=60&v=4){kind=small}
| const MyConfigSchema = z.object({ | ||
| temperature: z.number().describe("Sampling temperature"), | ||
| model: z.string(), | ||
| maxTokens: z.number(), | ||
| useCot: z.boolean().describe("Enable chain-of-thought reasoning"), | ||
| }).describe("MyConfig"); | ||
| ``` |
There was a problem hiding this comment.
maxTokens in TS vs max_tokens in Python — should we normalize TS serialization in sdks/typescript/src/opik/typeHelpers.ts to snake_case or add an explicit mapping so AgentConfig._resolve_from_backend receives matching keys?
Finding type: Type Inconsistency | Severity: 🔴 High
Want Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents:
Before applying, verify this suggestion against the current code. In
apps/opik-documentation/documentation/fern/docs/reference/typescript-sdk/agent-configurations.mdx
around lines 27-33 (the Zod schema example where `maxTokens` is used), the example uses
camelCase fields which conflicts with the Python SDK that expects snake_case keys.
Update the documentation example to use snake_case (e.g., max_tokens) or add a clear
note about automatic camelCase↔snake_case mapping. Then modify
sdks/typescript/src/opik/typeHelpers.ts (around lines 83-168) to canonicalize/serialize
schema field names to lowercase_snake_case when building prefixed backend keys (instead
of using the fieldName verbatim), and verify AgentConfig._resolve_from_backend in the
Python code (around lines 332-345) still accepts those keys; implement a consistent
mapping layer if needed so both SDKs read the same backend payload.
| ## Prompts in Configurations | ||
|
|
||
| Agent configurations have a direct connection to Opik's prompt management system. **Updating a prompt will automatically update the configuration** — when a prompt referenced by a configuration is updated, the configuration will reflect the updated prompt the next time it is fetched, without needing to publish a new configuration version. | ||
|
|
There was a problem hiding this comment.
Docs claim prompt updates auto-update configs, but commits are used for prompt fields via getPromptByCommit so fetched configs retain the old prompt until you publish a new version; should we reword the docs or change the implementation to clarify updates only flow through after publishing unless you explicitly refresh the config version?
Finding type: Logical Bugs | Severity: 🟠 Medium
Want Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents:
Before applying, verify this suggestion against the current code. In
apps/opik-documentation/documentation/fern/docs/reference/typescript-sdk/agent-configurations.mdx
around lines 206 to 209, the section titled “Prompts in Configurations” currently
claims that “Updating a prompt will automatically update the configuration … without
needing to publish a new configuration version.” This is incorrect because the SDK
serializes prompt fields as commit IDs and blueprints resolve prompts by commit, so a
configuration will continue to reference the old prompt commit until you publish a new
config version (or explicitly refresh the config version). Replace the existing sentence
with a concise clarification stating that prompt references are stored by commit ID,
that updates to prompts do not change already-published config versions, and that users
must publish a new agent config version (or use an explicit refresh mechanism) for
prompt changes to flow into that config; optionally add a short parenthetical note
pointing maintainers to serializeFields and Blueprint.resolvePrompts in the TypeScript
SDK (and the equivalent Python functions) for implementation details.
| --- | ||
| headline: Agent Configurations | Opik Documentation | ||
| og:description: Learn to manage agent configurations with versioning, environment deployments, and real-time updates using Opik's Python and TypeScript SDKs. | ||
| og:site_name: Opik Documentation | ||
| og:title: Agent Configurations | ||
| title: Agent Configurations | ||
| --- |
There was a problem hiding this comment.
agent_configurations.mdx uses snake_case, should we rename it and all references to agent-configurations.mdx?
Finding type: AI Coding Guidelines | Severity: 🟢 Low
Want Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents:
Before applying, verify this suggestion against the current code. In
apps/opik-documentation/documentation/fern/docs/tracing/agent_configurations.mdx around
lines 1-7 (the file header/frontmatter and filename), the filename uses snake_case but
the project requires descriptive kebab-case. Rename the file to agent-configurations.mdx
(perform git mv), and update every reference to the old path across the repository
(documentation links, sidebar/TOC entries, imports, build or CI config) to the new path.
Ensure the file's frontmatter/title remains unchanged and run a quick link-check or docs
build to verify no broken references remain.
| const client = new Opik(); | ||
|
|
||
| const prompt = await client.getPrompt({ name: "my-text-prompt" }); | ||
|
|
||
| const AgentWithPromptsSchema = z.object({ | ||
| summaryPrompt: z.string().describe("Summary prompt template"), | ||
| temperature: z.number(), | ||
| }).describe("AgentWithPrompts"); | ||
|
|
||
| await client.createAgentConfig( | ||
| AgentWithPromptsSchema, | ||
| { summaryPrompt: prompt!.prompt, temperature: 0.7 }, |
There was a problem hiding this comment.
summaryPrompt is set to the raw prompt!.prompt string so it serializes as type="string" and won't auto-update — should we pass a Prompt instance or use z.instanceof(Prompt) in the schema?
Finding type: Type Inconsistency | Severity: 🟠 Medium
Want Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents:
Before applying, verify this suggestion against the current code. In
apps/opik-documentation/documentation/fern/docs/tracing/agent_configurations.mdx around
lines 444 to 458, the TypeScript example sets summaryPrompt: prompt!.prompt (a raw
string), which serializes as type="string" and prevents the backend from
resolving/updating the prompt. Change the example to accept and pass a Prompt object:
update the schema field to use z.instanceof(Prompt) (or the appropriate Opik Prompt
validator) and import the Prompt type from the SDK, then pass prompt (the Prompt object)
as the value to createAgentConfig instead of prompt!.prompt so the configuration stores
a prompt reference that can auto-update. Ensure the example code shows the updated
import and value usage.
|
@aadereiko -> given I expect most users will instruct claude code/codex/cursor to instrument their apps to support this feature, what do you think about adding some kind of guidance on what to tell claude to to do using our skills? |
| import { Opik, track, ChatPrompt } from "opik"; | ||
| import { z } from "zod"; | ||
|
|
||
| const client = new Opik(); | ||
|
|
||
| const fallbackPrompt = await client.getChatPrompt({ name: "my-system-prompt" }); | ||
|
|
||
| const MyConfigSchema = z.object({ | ||
| temperature: z.number(), | ||
| model: z.string(), | ||
| maxTokens: z.number(), | ||
| systemPrompt: z.instanceof(ChatPrompt), |
There was a problem hiding this comment.
getAgentConfigVersion(..., fallback) example fetches client.getChatPrompt({ name: "my-system-prompt" }) right before the fallback, so when the backend is down the fallback never gets constructed — should we define/cache the fallback prompt locally (or document shipping it with the agent) instead of fetching it immediately?
Finding type: Logical Bugs | Severity: 🔴 High
Want Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents:
Before applying, verify this suggestion against the current code. In
apps/opik-documentation/documentation/fern/docs/reference/typescript-sdk/agent-configurations.mdx
around lines 144 to 165, the example calls client.getChatPrompt({ name:
"my-system-prompt" }) immediately before constructing the fallback, which will throw if
the Opik backend is unreachable and thus never demonstrate the fallback behavior.
Refactor the example to define a local/cached fallbackPrompt (e.g., construct a
ChatPrompt-like object or load a bundled prompt string) and use that in the fallback
object; optionally show a try/catch that attempts to fetch the remote prompt and falls
back to the local prompt if fetching fails. This ensures the fallback path can be
exercised when the backend is down and documents that consumers should bundle or cache
fallback prompts with their agent.
| ```typescript | ||
| import { Opik, track } from "opik"; | ||
| import { AgentConfigManager, agentConfigContext } from "opik"; | ||
| import { z } from "zod"; | ||
|
|
There was a problem hiding this comment.
AgentConfigManager mask example is duplicated in docs/tracing/agent_configurations.mdx, should we centralize it and reference/include it?
Finding type: Code Dedup and Conventions | Severity: 🟢 Low
Want Baz to fix this for you? Activate Fixer
aadereiko
force-pushed
the
sashaa/OPIK-5031/blueprints-docs
branch
from
8d01e62 to
10622e8
Compare
| const MyConfigSchema = z.object({ | ||
| temperature: z.number().describe("Sampling temperature"), | ||
| model: z.string(), | ||
| maxTokens: z.number(), | ||
| systemPrompt: z.instanceof(ChatPrompt).describe("System prompt for the agent"), | ||
| useCot: z.boolean().describe("Enable chain-of-thought reasoning"), | ||
| }).describe("MyConfig"); |
There was a problem hiding this comment.
MyConfigSchema is duplicated from the TypeScript tab in docs/tracing/agent_configurations.mdx, should we reuse/include/link that tab instead of copying the snippet?
Finding type: Code Dedup and Conventions | Severity: 🟢 Low
Want Baz to fix this for you? Activate Fixer
4 participants
Details
Change checklist
Issues
AI-WATERMARK
AI-WATERMARK: [yes|no]
Testing
Documentation