feat(examples): add evaluation and optimization pipeline (#91)

[xyaohubery]

Summary

Add an automated evaluation and prompt optimization pipeline example.

• Built-in eval test cases with keyword-based scoring
• Auto-regression across prompt iterations
• Iterative prompt optimization with analysis

Fixes #91

This is a split from the original PR #166, addressing only issue #91 per reviewer feedback.

Co-Authored-By: Claude noreply@anthropic.com

[helloopenworld]

AI Code Review

event.content 确实存在（作为 LlmResponse 的属性）。run_agent.py 中的 print(event.content, end="") 会打印一个 Content 对象，而不是文本——参考 quickstart，它会遍历各个部分以获取 part.text。这是一个微小的可用性问题，但次要的致命问题是缺少 app_name 以及 runner.run(prompt) 是错误的 API 调用。

现在我已经掌握了足够的信息。让我来撰写审查意见。## 发现的问题

🚨 Critical

• examples/eval_optimization/run_agent.py:218-219：Runner 构造与方法调用均与 SDK 实际 API 不匹配，示例无法运行
  • Runner.__init__ 要求关键字参数 app_name（见 trpc_agent_sdk/runners.py:186），此处未传会直接 TypeError；且 Runner 没有 run 方法，正确的入口是 run_async，其签名为 run_async(*, user_id, session_id, new_message, ...)（trpc_agent_sdk/runners.py:361），全为关键字参数且需要 Content 类型，而此处以位置参数传了一个字符串 prompt。需改为 Runner(app_name=..., agent=agent, session_service=session_service) 并 async for event in runner.run_async(user_id=..., session_id=..., new_message=Content(parts=[Part.from_text(text=prompt)]))，参考 examples/quickstart/run_agent.py:27,60。

  • ...
    runner = Runner(agent=agent, session_service=session_service)
    async for event in runner.run(prompt):
    ...

⚠️ Warning

• examples/eval_optimization/run_agent.py:219-221：直接 print(event.content) 输出的是 Content 对象，不会打印模型文本

  • event.content 是 Content 对象而非字符串（trpc_agent_sdk/events/_event.py:217），需遍历 event.content.parts 取 part.text 并跳过 thought/function_call 等，否则示例运行后看不到任何有效输出。建议对齐 examples/quickstart/run_agent.py:60-82 的处理方式。

• examples/eval_optimization/agent/tools.py:159-185：optimize_prompt 用 version = int(time.time()) 作为版本号，无法保证单调且与 prompt 变更无关

  • 同一秒内多次调用会得到相同 version，违背“prompt iteration”语义，且 time.time() 可能为浮点被 int 截断。建议改用调用方传入或模块内自增计数器作为版本号。

• examples/eval_optimization/agent/tools.py:150-156：score_response 对空 expected_keywords 返回满分，可能掩盖“无校验”用例的回归

  • 当 expected_keywords 为空时直接得 1.0，会让没有定义期望关键词的用例永远“通过”，无法发现回归。建议对空关键词返回 0.0 或显式区分“无校验”状态。

总结

新增示例整体结构与 SDK 用法基本对应，但 run_agent.py 的 Runner 构造与调用方式与当前 SDK API 严重不符，示例完全无法运行，属于必须修复的 Critical 问题；其余为输出展示、版本号生成与评分边界等建议项。

测试建议

• 补充一个最小冒烟测试（或在 CI 中对示例做 import/构造校验），至少断言 create_agent() 可构造、Runner(app_name=..., agent=..., session_service=session_service) 不抛异常，避免 API 漂移再次导致示例失效。

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@12388ad). Learn more about missing BASE report.

Additional details and impacted files

@@            Coverage Diff             @@
##             main        #289   +/-   ##
==========================================
  Coverage        ?   88.44269%           
==========================================
  Files           ?         491           
  Lines           ?       46118           
  Branches        ?           0           
==========================================
  Hits            ?       40788           
  Misses          ?        5330           
  Partials        ?           0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.