Clarify workflow span criteria and add reference scenarios for langchain and openai agents

[lmolkova]

• Clarify that invoke_workflow span is reported when framework API implies composite operation
• add examples covering OpenAI Agents Runner.run (explicitly documented as workflow) and similar ADK API
• add recommendation to document per-framework criteria on when to emit workflow vs agent

Fun fact:

Code like this in OpenAI Agents (and similar on with ADK)

agent_b = Agent(
    name="Agent B",
    instructions="You are Agent B. You just received a transferred request. Answer it politely."
)

agent_a = Agent(
    name="Agent A",
    instructions="You are Agent A. Always transfer the request to Agent B immediately.",
    handoffs=[agent_b]
)

result = await Runner.run(agent_a, "Help me compare metrics and traces.", run_config=RunConfig(workflow_name="sequential-agents"))

Produces traces like this:

Where agent A and agent B are siblings.

In the future, OpenAI and ADK can document additional heuristics (e.g. if runner.run is called with a single agent, no agents-as-tools, no sub-agents, no handoff agents, etc).

Motivation

It's not clear today who and when should produce workflow spans. It's also not clear what should be used as a workflow name, resulting in static types like StateGraph being used that talk about the implementation details and topology rather than anything about application and its workflows.

Checklist

• Motivation section filled in above
• Reference scenarios updated for affected libraries
• Towncrier fragment added under changelog.d/ for any change to the conventions that a consumer would care about. Editorial changes (typos, pure rewording, repo tooling) don't need an entry.

See [CONTRIBUTING.md]

[Copilot]

Pull request overview

Updates the GenAI semantic conventions guidance around when to emit an invoke_workflow span (vs invoke_agent), and extends the Python reference scenarios so the workflow span is demonstrated for additional frameworks (LangGraph/LangChain and OpenAI Agents). Regenerates scenario data.json and updates the aggregated reference coverage reports/index accordingly.

Changes:

• Refines invoke_workflow span criteria text in the model (and corresponding generated docs) with clearer framework-oriented guidance and concrete examples.
• Adds new workflow-span reference runs to the OpenAI Agents and LangChain scenarios, including invoke_workflow attribute emission and updated data.json.
• Updates reference reports and the reference README index to include the newly supporting libraries for invoke_workflow (and related span coverage).

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
reference/scenarios/openai-agents/scenario.py	Adds a workflow-run example that emits an invoke_workflow span and attributes for OpenAI Agents.
reference/scenarios/openai-agents/data.json	Records observed invoke_workflow attribute coverage for the OpenAI Agents scenario.
reference/scenarios/langchain/scenario.py	Adds a LangGraph workflow-run example emitting an invoke_workflow span and introduces a tool span example.
reference/scenarios/langchain/data.json	Records observed invoke_workflow / execute_tool attribute coverage for the LangChain scenario.
reference/reports/invoke-workflow-span.md	Updates workflow span coverage report to include LangChain and OpenAI Agents.
reference/reports/execute-tool-span.md	Updates execute_tool coverage report to include LangChain among supporting libraries (but needs a correction noted in review).
reference/README.md	Updates the reference report index tables to include LangChain/OpenAI Agents for workflow/tool spans.
model/gen-ai/spans.yaml	Refines the invoke_workflow span guidance and examples in the semantic conventions model.
docs/gen-ai/gen-ai-agent-spans.md	Mirrors the updated invoke_workflow guidance in the generated docs page.

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on maintainers · refreshed 2026-08-10 14:02 UTC

Merge when ready.

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Anything look wrong? Report it with what you expected; it helps us improve the dashboard.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

[trask]

Lightly filtered AI-generated feedback — push back freely