feat(claude-agent-sdk): enhance tutorials with improved notebooks, agents, and documentation

[costiash]

Summary

This PR enhances the claude_agent_sdk/ tutorial section with improvements across notebooks, agent implementations, utilities, and new documentation.

📋 See companion issue for detailed breakdown and discussion: #313

---

Changes Overview

📓 Notebooks (Enhanced)

File	Changes
00_The_one_liner_research_agent.ipynb	Richer outputs, better visualization, cleaner examples
01_The_chief_of_staff_agent.ipynb	Improved flow, cleaner cell outputs
02_The_observability_agent.ipynb	Enhanced MCP examples, better output formatting

🤖 Agent Implementations (Improved)

File	Changes
research_agent/agent.py	Cleaner code structure, better error handling
observability_agent/agent.py	Enhanced visualization, improved token/cost reporting
chief_of_staff_agent/agent.py	Refactored for clarity

🛠️ Utilities

File	Changes
utils/agent_visualizer.py	Major refactor for maintainability
utils/html_renderer.py	NEW - Rich HTML visualization for Jupyter environments

📚 Documentation (New)

File	Purpose
docs/README.md	Documentation overview
docs/ADDITIONS.md	Summary of all enhancements
docs/CODEBASE_OVERVIEW.md	Architecture guide for the tutorial
docs/TROUBLESHOOTING.md	Common issues and solutions

⚙️ Config

• pyproject.toml - Added pyyaml dependency

---

Why This PR?

After working through the Claude Agent SDK tutorials, I found opportunities to:

1. Improve learning experience with clearer outputs and visualizations
2. Add missing documentation to help newcomers understand the codebase
3. Enhance agent implementations with better code organization
4. Create reusable utilities for rich notebook visualizations

---

Notes for Reviewers

• Happy to split this PR if preferred - see #313 for breakdown by category
• All Python files pass ruff check
• No breaking changes to existing functionality
• Backwards compatible with existing usage patterns

---

Screenshots of the new visualizer against the old version

---

---

Test Plan

• Verify notebooks run without errors
• Check agent implementations work as documented
• Validate HTML renderer produces correct output
• Review documentation accuracy

[PedramNavid]

PR Review

Recommendation: REQUEST_CHANGES

Summary

This is a substantial PR (5,225 additions, 686 deletions) that enhances the Claude Agent SDK tutorials with improved notebooks, new visualization utilities, and documentation. While the core work is high-quality, there are critical issues around linting/formatting, documentation accuracy, and an important policy concern about supplementary markdown files.

Actionable Feedback (15 items)

Critical (must fix):

• Run uv run ruff format . && uv run ruff check --fix . in claude_agent_sdk/ - notebooks and utils fail formatting/linting
• 00_The_one_liner_research_agent.ipynb (cell with %%capture) - Uncomment %pip install or add explanation why it's commented
• Remove supplementary docs/: Per repo guidelines, avoid creating supplementary markdown files like ADDITIONS.md, CODEBASE_OVERVIEW.md, TROUBLESHOOTING.md within cookbook directories. These add maintenance burden. Keep documentation in notebook cells or main README instead.
• Verify model names claude-opus-4-5 and claude-sonnet-4-5 are valid API aliases (repo CLAUDE.md specifies full IDs like claude-sonnet-4-5-20250929)

Important:

• research_agent/agent.py:24-26 - Remove sys.path.insert() hack, add instructions for uv pip install -e . instead
• Verify numpy and pandas dependencies are actually used in the PR, remove if not needed
• utils/agent_visualizer.py:85-95 - Add prominent warning in notebook about global state not being thread-safe, or refactor to use contextvars
• docs/ADDITIONS.md and docs/README.md reference non-existent files (03_The_learning_path_test_notebook.ipynb, 04_Python_Implementation_Mission/) - if not removing docs, fix these references

Suggestions:

• utils/html_renderer.py:207 - Consider escape=True for DataFrame HTML rendering (security)
• chief_of_staff_agent/scripts/decision_matrix.py:44 - Fix the # type: ignore properly
• Add docstring examples to utils/agent_visualizer.py
• Add consistent type hints across all agent modules

Detailed Review

Policy Concern: Supplementary Documentation Files

The PR adds four new markdown files in claude_agent_sdk/docs/:

• ADDITIONS.md (223 lines)
• CODEBASE_OVERVIEW.md (450 lines)
• TROUBLESHOOTING.md (204 lines)
• README.md

Why this is problematic:

1. Maintenance burden: These files will become outdated as the codebase evolves
2. Already outdated: ADDITIONS.md references non-existent files (03_The_learning_path_test_notebook.ipynb, 04_Python_Implementation_Mission/)
3. Duplication: Architecture and troubleshooting info should live in notebook cells where it's most discoverable
4. Repository guidelines: Per CLAUDE.md rule 6, avoid creating supplementary markdown files within cookbook directories

Recommendation: Move essential content (like buffer overflow troubleshooting) into notebook markdown cells and remove the docs/ directory.

Code Quality

Strengths:

• Well-designed module split between agent_visualizer.py and html_renderer.py
• Good environment detection with _is_jupyter()
• Proper use of html.escape() for security
• Excellent type hints in decision_matrix.py

Issues:

• Global state _subagent_context with thread-safety warning - problematic for async code
• sys.path.insert() pattern is fragile
• Linting/formatting failures across notebooks and utils

Security

• HTML rendering properly escapes user content ✓
• One concern: df.to_html(escape=False) could be XSS vector
• No hardcoded secrets ✓

Positive Notes

• Problem-focused learning approach in notebook introductions
• Progressive complexity (stateless → stateful → production)
• The HTML timeline visualization is polished and professional
• Excellent TypedDict usage in decision_matrix.py

---

Path Forward

The core notebook and utility enhancements are valuable. To get this PR ready for merge:

1. Fix linting/formatting - Quick fix with ruff commands
2. Remove or relocate docs/ - Move essential content to notebook cells
3. Fix sys.path.insert pattern - Use proper package installation
4. Verify dependencies - Remove unused numpy/pandas if not needed

Thank you for the substantial effort! The visualization utilities and notebook improvements add real value once the policy and technical issues are addressed.

🤖 Generated with Claude Code

[Wirasm]

Claude Model Usage Review

I've reviewed the changed files in this PR for Claude model usage against the current public models list from Anthropic's documentation.

✅ Summary

All model references in this PR use valid, current public Claude models. No deprecated or internal models were found.

📊 Models Used

The PR updates model references from various models to primarily use:

1. claude-opus-4-5 ✅ (Current, Public)

   • API ID: claude-opus-4-5-20251101
   • This is the latest Opus model and is appropriate for the use cases in this PR

2. claude-sonnet-4-5 ✅ (Current, Public)

   • API ID: claude-sonnet-4-5-20250929
   • Still used in several places, which is appropriate

3. claude-opus-4-1 - ⚠️ REMOVED (Good!)

   • This older Opus model was removed from the code, which is a positive change
   • Previously used in the Chief of Staff planning example

🎯 Key Changes

Notebooks Updated:

• 00_The_one_liner_research_agent.ipynb: Updated to use claude-opus-4-5
• 01_The_chief_of_staff_agent.ipynb: Updated planning example from claude-opus-4-1 to claude-opus-4-5
• 02_The_observability_agent.ipynb: Updated to use claude-opus-4-5

Agent Code Updated:

• research_agent/agent.py: DEFAULT_MODEL set to claude-opus-4-5
• observability_agent/agent.py: DEFAULT_MODEL set to claude-opus-4-5
• chief_of_staff_agent/agent.py: Updated to claude-opus-4-5

💡 Recommendations

While all models are valid, consider these best practices for better maintainability:

1. Consider using versioned aliases (optional):

   • Currently using: claude-opus-4-5, claude-sonnet-4-5
   • These ARE the recommended alias format per Anthropic's docs
   • For production, you could use fully versioned IDs like claude-opus-4-5-20251101 for stability, but aliases are fine for examples

2. Consistency is good: The PR does a good job standardizing on claude-opus-4-5 as the default across examples, which demonstrates the capabilities of the most advanced model.

3. Model selection rationale: Using Opus for these examples makes sense given they showcase complex agent capabilities (planning, observability, research).

✅ Verdict

No issues found. All model references are:

• ✅ From the current public models list
• ✅ Using proper model naming conventions
• ✅ No deprecated models remain
• ✅ No internal/non-public model names

This PR successfully updates the codebase to use the latest Claude models. Great work! 🎉

[costiash]

Hey all and thank for the reviews!
I'll handle the issues mentioned by @PedramNavid ASAP!
Thanks again for the genuine feedback despite the PR being so comprehensive

[costiash]

Addresses all feedback from @PedramNavid's review.

Critical Issues Fixed

• Run ruff format and ruff check - all 15 Python files pass
• Uncomment %pip install in 00_The_one_liner_research_agent.ipynb
• Remove supplementary docs/ directory per repo guidelines
  • Deleted: ADDITIONS.md, CODEBASE_OVERVIEW.md, TROUBLESHOOTING.md, README.md
• Model names verified (claude-opus-4-5, claude-sonnet-4-5 are valid aliases)

Important Issues Addressed

• sys.path.insert() hack removed from research_agent/agent.py
• Verified dependencies: kept pandas/markdown (used by html_renderer.py),
  removed unused numpy and pandas-stubs
• Thread-safety warning already present in agent_visualizer.py (lines 106-111)
• docs/ references now removed (files deleted)

Suggestions Implemented

• escape=True already added for DataFrame HTML (html_renderer.py:207,221)
• type: ignore fixed with proper TypedDict in decision_matrix.py
• Docstring examples added in agent_visualizer.py
• Consistent type hints across all agent modules

Additional Cleanup

• Removed temporary directories: .vscode/, plans/, extra output reports
• Cleaned pyproject.toml: removed dev dependencies (mypy, ruff, pytest),
  testing config, and unused numpy dependency

Code Quality Verification

• All Python files pass ruff check
• All Python files pass ruff format --check
• All agent modules pass mypy type checking
• Project structure now matches upstream exactly

Additional checks

• Verify notebooks run without errors
• Check agent implementations work as documented
• Validate HTML renderer produces correct output
• Review documentation accuracy

Ready for re-review!

[PedramNavid]

PR Review

Recommendation: APPROVE ✅

Summary

This PR significantly enhances the claude_agent_sdk tutorial section with improved notebooks, agent implementations, visualization utilities (new html_renderer.py), and documentation. The code quality is high with proper type annotations, error handling, and security measures.

Actionable Feedback (2 items)

• claude_agent_sdk/research_agent/agent.py:83 - Fix docstring that incorrectly states "claude-sonnet-4-5" as default when the actual default is "claude-opus-4-5" (line 30)
• claude_agent_sdk/01_The_chief_of_staff_agent.ipynb and 02_The_observability_agent.ipynb - Verify these notebooks have proper Terminal Learning Objectives (TLOs) matching the style guide pattern used in notebook 00

Detailed Review

Code Quality

Excellent improvements across the board:

• Comprehensive type annotations added to all agent files (modern str | None syntax)
• Proper error handling with try/except blocks
• Clean separation of concerns between html_renderer and agent_visualizer
• All linting and formatting checks pass
• Context managers (async with) used correctly

Minor concerns:

• utils/agent_visualizer.py:112-116 uses global state for subagent tracking that's explicitly not thread-safe. While this works for notebooks, consider using contextvars for async-safe context management in the future.
• utils/html_renderer.py:270 - Markdown rendering passes through without explicit sanitization. While markdown typically sanitizes by default and the risk is low (agent output, not direct user input), consider adding explicit sanitization.

Security

• ✅ Proper use of html.escape() throughout HTML rendering
• ✅ escape=True in pandas DataFrame rendering
• ✅ No hardcoded API keys (all use dotenv.load_dotenv())
• ✅ No secrets committed
• ⚠️ Low-risk: Markdown-to-HTML conversion could use explicit sanitization

Suggestions

1. Add file size validation in _image_to_base64() to prevent memory issues with large images
2. Consider adding cost monitoring guidance in agent docstrings
3. Type protocols would improve IDE support vs current duck typing with msg.__class__.__name__

Positive Notes

• Visualization enhancements: Auto-detection of Jupyter vs terminal, rich HTML cards, box-drawing fallbacks
• Pedagogical structure: Notebook 00 has excellent TLO structure, clear problem-focused intro
• Model usage: Using latest claude-opus-4-5 model
• Dependencies: Graceful fallbacks for optional deps (IPython, pandas, markdown)
• Documentation: Comprehensive module docstrings with examples

🤖 Generated with Claude Code

[PedramNavid]

Thanks for that @costiash ! overall looks good, could you update the description of the PR with examples from the new implementations for the visualizer? Both the html renderer and the original please. Screenshots will suffice

Also note there's some merge conflicts that would need to be resolved but otherwise these changes look great, thanks for the contribution!

[costiash]

Thanks for that @costiash ! overall looks good, could you update the description of the PR with examples from the new implementations for the visualizer? Both the html renderer and the original please. Screenshots will suffice

Also note there's some merge conflicts that would need to be resolved but otherwise these changes look great, thanks for the contribution!

Rebased onto main to resolve merge conflicts. No content changes—just incorporated the latest upstream commits (cbcc709, 9fadbb7, b4a8aae). All linting checks pass and added couple of screenshots to the PR. Ready for re-review when you have a moment! 🙏

[PedramNavid]

thank you!

[PedramNavid]

oh sorry -- one final requirement is that commits must have verified signatures before i can merge them in. Could you follow these steps? I shouldve flagged this earlier. https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification

[costiash]

oh sorry -- one final requirement is that commits must have verified signatures before i can merge them in. Could you follow these steps? I shouldve flagged this earlier. https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification

Done :)