feat: add standalone DeepAgent observability

[aharonamir]

Paired: GitHub #427 ↔ GitCode !2254

This was generated by AI during triage.

Summary

Implements PR1 from the observability RFC.

Refs #426.

Changes:

• Adds explicit opt-in standalone DeepAgent observability through create_deep_agent()/resolve_deep_agent_parts().
• Adds standalone agent root spans so task-loop and single-round DeepAgent runs can emit a complete trace outside team context.
• Starts standalone root spans from a clean OTel context so sequential invocations do not inherit an ended span.
• Reuses the existing ObservabilityRail and parent-resolution path for LLM/tool spans.
• Keeps observability imports lazy so normal harness imports do not require optional OTel dependencies.
• Adds regression coverage for standalone task-loop, single-round, sequential invocation, and factory wiring behavior.

Validation

• env UV_CACHE_DIR=/tmp/uv-cache uv run --extra observability pytest tests/unit_tests/agent_teams/observability/test_observability.py tests/unit_tests/harness/test_factory_llm_retry_rail.py -q
• git diff --check

Notes

The broader team-run mock test tests/unit_tests/agent_teams/observability/test_team_observability_mock_llm.py::test_leader_single_iteration_trace_via_runner still times out with zero mock LLM calls when run alone. The direct observability callback/rail suite passes.

Linked Closing Issues:

• Fixes RFC: Complete observability coverage for DeepAgent, sessions, metrics, and cost #426

[openjiuwen-collaboration-bot]

head_sha: 15b60e3017d77b540f7d81b7f80cc0bc07bb0b24

变更摘要

此变更为独立运行的 DeepAgent（非团队上下文）添加了显式的可观测性（Observability）支持。通过在 ObservabilityRail 中引入独立的 agent 根 span 机制，使得无团队包裹的 task-loop 和单轮 DeepAgent 调用也能产出完整的 trace。同时，在 create_deep_agent() / resolve_deep_agent_parts() 工厂函数中新增 observability_config 参数，支持通过配置一键开启可观测性并自动注入 ObservabilityRail。所有可观测性相关导入均保持懒加载，避免对未安装 OTel 依赖的正常使用造成影响。

主要改动

• 独立 agent 根 span 的创建与关闭：在 ObservabilityRail 中新增 _open_standalone_root_if_needed 和 _close_standalone_root 方法。当检测到无团队根 span（get_team_span() 为 None）且 agent 不属于任何团队时，自动创建 agent.<name> 根 span 并从干净的 OTel Context 启动，确保 task-iteration、invoke、LLM 和 tool span 共享同一 trace；调用结束时关闭根 span 并清理环境回退引用。

• before_invoke / after_invoke 行为调整：before_invoke 中原先在没有团队 span 时直接跳过，现改为先调用 _open_standalone_root_if_needed 再继续判断；after_invoke 中原先跳过非 invoke 类 span 时直接返回，现增加 _close_standalone_root 调用，确保独立根 span 在任务循环路径上也能正确关闭。

• Span 上下文管理函数扩展：在 span_context.py 中新增 set_ambient_root_span、get_trace_root_span 和 clear_ambient_root_span 三个函数，复用现有的 _ambient_team_span 存储，统一管理团队根 span 和独立 agent 根 span 的进程级回退引用。

• 工厂函数新增 observability_config 参数：resolve_deep_agent_parts 和 create_deep_agent 新增 observability_config: ObservabilityConfig | None 参数。当配置启用且尚未初始化时自动调用 init_observability，并在用户未手动提供 ObservabilityRail 时自动追加到 rails 列表中。

• 新增回归测试覆盖：在 test_observability.py 中增加三个测试用例，分别验证独立 task-loop trace、独立单轮 invoke trace 以及顺序调用时根 span 互不继承；在 test_factory_llm_retry_rail.py 中增加两个测试用例，验证工厂函数自动注入 rail 和不重复添加手动 rail 的行为。

[openjiuwen-collaboration-bot]

head_sha: 15b60e3017d77b540f7d81b7f80cc0bc07bb0b24

代码审查

✅ 未发现问题

[openjiuwen-collaboration-bot]

head_sha: 15b60e3017d77b540f7d81b7f80cc0bc07bb0b24

任务名称	结果	日志操作
静态检查	✅SUCCESS	点此跳转
防投毒检查	✅SUCCESS	点此跳转
开源合规检查	✅SUCCESS	点此跳转
UT测试	✅SUCCESS	点此跳转
ST测试	N/A	N/A
build 编译包	N/A	N/A
ruff codecheck	✅SUCCESS	N/A