Fix Python tracing examples and add async guidance

[parteeksingh24]

Summary by CodeRabbit

• Documentation
  • Updated Python tracing examples to use standard with-based span management, including async scenarios and nested spans.
  • Added guidance on language-specific patterns (JS/TS vs Python), async operations, error handling, semantic conventions, performance, and viewing traces.
  • Included new example blocks and formatting improvements for clarity.
  • Revised Python project structure example to reflect the updated agents package directory name.
  • Synced API reference to reflect the new span usage pattern.

[coderabbitai]

Walkthrough

Documentation updates replace async span context managers with synchronous ones in Python examples, expand tracing guides with new sections and patterns, adjust error-handling examples, and update a Python project structure path from agents/ to agentuity_agents/. API reference examples are aligned to the synchronous span usage.

Changes

Cohort / File(s)	Summary
Tracing docs: sync span context managers and expanded guidance content/Guides/agent-tracing.mdx	Switched Python examples from async to sync context managers for spans; added sections on language-specific patterns, async work within sync spans, nested spans, error handling, semantic conventions, performance, and viewing traces; updated examples and formatting.
Architecture doc: directory rename content/Introduction/architecture.mdx	Updated Python project structure example to rename directory from agents/ to agentuity_agents/.
Python SDK API reference: span example sync-ified content/SDKs/python/api-reference.mdx	Replaced async with span example with with for OpenTelemetry span usage; no other logic changes.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor Client
  participant App
  participant Tracer
  participant Span
  participant AsyncTask as Async Operation

  Client->>App: Handle request
  App->>Tracer: start_as_current_span("process-data")
  activate Tracer
  Tracer-->>App: returns Span (sync context)
  deactivate Tracer
  rect rgba(200,235,255,0.3)
    note over App,Span: Synchronous with-block owns span lifecycle
    App->>Span: set_attribute / add_event
    App->>AsyncTask: await do_work()
    AsyncTask-->>App: result / error
    App->>Span: record_exception (on error)
  end
  App-->>Span: exit with-block (closes span)
  App-->>Client: Response

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

I twitch my ears at spans that run,
From async hops to sync we’ve spun.
With nested trails and traces clear,
I bound through logs without a fear.
A nibble of errors, handled just right—
agentuity_agents/ now in sight!
Thump-thump—ship it, bright as byte.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly summarizes the primary updates by indicating fixes to Python tracing examples and the inclusion of async guidance, which aligns well with the documented changes.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch parteek/update-python-info

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d013b39 and fa47599.

📒 Files selected for processing (3)

• content/Guides/agent-tracing.mdx (4 hunks)
• content/Introduction/architecture.mdx (1 hunks)
• content/SDKs/python/api-reference.mdx (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

content/SDKs/**

📄 CodeRabbit inference engine (.cursor/rules/overview.mdc)

Store SDK documentation in /content/SDKs

Files:

• content/SDKs/python/api-reference.mdx

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Workers Builds: docs

🔇 Additional comments (3)

content/Introduction/architecture.mdx (1)

136-139: Python agents directory rename looks consistent.

The updated directory name lines up with the broader guidance and removes the ambiguity between Python and JS layouts.

content/SDKs/python/api-reference.mdx (1)

1393-1411: Span context manager usage now matches the OpenTelemetry API.

The synchronous with pattern is the correct approach and keeps the async workload inside the block intact.

content/Guides/agent-tracing.mdx (1)

62-148: Great clarification on Python span scoping.

Documenting the synchronous context manager and contrasting it with JavaScript improves accuracy and developer clarity.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	docs	fa47599	Sep 24 2025, 11:46 PM