Skip to content

docs(weave): document linked agent eval traces#2930

Open
bcsherma wants to merge 5 commits into
mainfrom
codex/link-agent-evals-docs
Open

docs(weave): document linked agent eval traces#2930
bcsherma wants to merge 5 commits into
mainfrom
codex/link-agent-evals-docs

Conversation

@bcsherma

@bcsherma bcsherma commented Jul 17, 2026

Copy link
Copy Markdown
Member

Summary

  • Documents that Python agent calls must run inside the EvaluationLogger.log_prediction() context to link their spans to evaluation results.
  • Adds a focused OpenAI Agents SDK example showing the context, output, score, and example ID.
  • Documents every raw weave.eval.* OpenTelemetry attribute, including the two call IDs required for evaluation and result linkage.
  • Adds Python and TypeScript examples for manually stamped spans and explains how to retrieve the linkage IDs from the evaluation results API.
  • Adds a distributed Python example that creates a predict_and_score call, propagates both call IDs to an external agent service, and stamps the receiving OTel span.
  • Clarifies that automatic evaluation-to-agent span linking is Python-only and that TypeScript requires manual OTel attributes with both call IDs.
  • Shows how to open evaluation-linked spans in the Weave UI.

Validation

  • npx mint@latest validate
  • The new OpenAI Agents SDK, Agents OTel endpoint, and evaluation results API links resolve.

@mintlify

mintlify Bot commented Jul 17, 2026

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
wandb 🟢 Ready View Preview Jul 17, 2026, 7:09 PM

@github-actions

github-actions Bot commented Jul 17, 2026

Copy link
Copy Markdown
Contributor

📚 Mintlify Preview Links

🔗 View Full Preview

📝 Changed (1 total)

📄 Pages (1)

File Preview
weave/guides/evaluation/evaluation_logger.mdx Evaluation Logger

🤖 Generated automatically when Mintlify deployment succeeds
📍 Deployment: 359bc68 at 2026-07-24 14:38:45 UTC

@github-actions

github-actions Bot commented Jul 17, 2026

Copy link
Copy Markdown
Contributor

🔗 Link Checker Results

⚠️ Some issues were detected

Preview: https://wb-21fd5541-codex-link-agent-evals-docs.mintlify.site

Full Github Actions output

@NiWaRe NiWaRe left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor feedback to make sure everyone understands - great otherwise thanks for the fast turn around!!

| Attribute | Type | Description |
| --- | --- | --- |
| `weave.eval.run_id` | string | The call ID of the evaluation run (`Evaluation.evaluate`). Required to include the span in the evaluation-level **View spans** result. |
| `weave.eval.predict_and_score_call_id` | string | The call ID of the `Evaluation.predict_and_score` operation for a specific result and trial. Set this together with `weave.eval.run_id` to link the span to that result. |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe clearer if we include a quick example of how to create and propagate both IDs in above example?

Should be very similar but just to make sure the creation and propagation of the predict_and_score is also clear - from my understanding it is auto-created when a new prediction is logged and you would pass it along the external agent invocation?

@NiWaRe NiWaRe left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great example now!

Comment thread weave/guides/evaluation/evaluation_logger.mdx Outdated
Comment thread weave/guides/evaluation/evaluation_logger.mdx Outdated
Apply documentation-review changes to the eval-linking guide:
- standardize variable names to prediction/predictions
- standardize placeholders to [YOUR-TEAM]/[YOUR-PROJECT]
- replace "stamp" with "set"; label attribute table (Required)/(Optional)
- restructure "Link agent traces to evaluations" with situation-led
  subheadings and an orienting decision paragraph
- add "not available in TypeScript" tabs to Python-only examples, plus a
  Note clarifying the TypeScript raw-OTel path
- point the destination to the /agents/otel/v1/traces endpoint and link
  the Export a GenAI trace reference
- drop the per-example "View spans" UI step
- unify terminology (linking attributes, OTel span)
- focus the receiving-side example highlight on the two linking lines

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a how-to link to the newly merged 'Send OpenTelemetry spans to the
Agents view' guide alongside the endpoint reference, so readers have both
the conceptual pipeline setup and the endpoint spec.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Split the how-to guide and endpoint-spec links into a bulleted list and
keep the attribute-propagation rule with the send-to-project instruction.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants