jaspersoft-agent-learn/step_01_tools/main.py

"""
Step 01: 工具系统基础 - 主程序

运行方式：
    cd step_01_tools
    python main.py
"""

from concept import (
    ToolRegistry,
    CalculatorTool,
    SearchTool,
    JaspersoftCodeGeneratorTool
)


def main():
    """演示工具系统的完整使用流程"""

    print("=" * 70)
    print(" Step 01: 理解 Tool - 工具系统基础")
    print("=" * 70)
    print()

    # ═══════════════════════════════════════════════════════════════════════
    # 场景：构建一个 Jaspersoft 报表助手的工具集
    # ═══════════════════════════════════════════════════════════════════════

    print("📦 场景：构建 Jaspersoft 报表助手")
    print("-" * 70)
    print("""
假设我们要构建一个 AI 助手，帮助用户：
    1. 根据需求生成 JRXML 代码
    2. 验证生成的代码是否正确
    3. 计算报表的统计数据
    4. 搜索相关的报表模板

我们可以设计以下工具：
    - jrxml_generator: 生成 JRXML 代码
    - jrxml_validator: 验证 JRXML 语法
    - calculator: 计算统计数据
    - web_search: 搜索报表模板
""")

    # ═══════════════════════════════════════════════════════════════════════
    # 步骤 1：创建工具注册表
    # ═══════════════════════════════════════════════════════════════════════

    print("\n📋 步骤 1: 创建工具注册表")
    print("-" * 40)

    registry = ToolRegistry()
    print("✓ 创建了空的工具注册表")
    print(f"  当前注册工具数量: {len(registry.list_tools())}")

    # ═══════════════════════════════════════════════════════════════════════
    # 步骤 2：注册工具
    # ═══════════════════════════════════════════════════════════════════════

    print("\n🔧 步骤 2: 注册工具")
    print("-" * 40)

    # 注册各种工具
    registry.register(CalculatorTool())
    print("✓ 注册计算器工具")

    registry.register(SearchTool())
    print("✓ 注册搜索工具")

    registry.register(JaspersoftCodeGeneratorTool())
    print("✓ 注册 JRXML 生成工具")

    print(f"\n  当前注册工具数量: {len(registry.list_tools())}")

    # ═══════════════════════════════════════════════════════════════════════
    # 步骤 3：查看可用工具
    # ═══════════════════════════════════════════════════════════════════════

    print("\n📜 步骤 3: 查看可用工具")
    print("-" * 40)

    for tool_info in registry.list_tools():
        print(f"\n  [{tool_info['name']}]")
        # 截取描述的前100个字符
        desc = tool_info['description'].strip().replace('\n', ' ')[:100]
        print(f"      {desc}...")

    # ═══════════════════════════════════════════════════════════════════════
    # 步骤 4：执行工具
    # ═══════════════════════════════════════════════════════════════════════

    print("\n\n⚡ 步骤 4: 执行工具")
    print("-" * 40)

    # 场景：用户想要生成一个销售报表
    user_requirement = "生成一个销售报表，显示月度汇总"

    print(f"\n  用户需求: {user_requirement}")

    # 4.1 先搜索相关的模板
    print("\n  4.1 搜索相关模板...")
    search_result = registry.execute("web_search", query="JasperReports 销售报表模板")
    if search_result.success:
        print(f"      找到 {len(search_result.result)} 个相关模板")
        for i, item in enumerate(search_result.result[:2], 1):
            print(f"        {i}. {item['title']}")

    # 4.2 生成 JRXML
    print("\n  4.2 生成 JRXML 代码...")
    generate_result = registry.execute(
        "jrxml_generator",
        requirement=user_requirement,
        context="参考销售报表模板"
    )
    if generate_result.success:
        print(f"      ✓ 生成成功!")
        print(f"      代码长度: {len(generate_result.result)} 字符")
        print(f"      代码预览:")
        print("      " + "-" * 30)
        for line in generate_result.result.split('\n')[:5]:
            print(f"      {line}")
        print("      ...")

    # 4.3 计算统计
    print("\n  4.3 计算统计...")
    calc_result = registry.execute("calculator", expression="10 + 20 + 30")
    if calc_result.success:
        print(f"      10 + 20 + 30 = {calc_result.result}")

    # ═══════════════════════════════════════════════════════════════════════
    # 步骤 5：错误处理
    # ═══════════════════════════════════════════════════════════════════════

    print("\n\n⚠️  步骤 5: 错误处理演示")
    print("-" * 40)

    # 场景：用户尝试除以零
    print("\n  尝试执行: calculator(expression='10 / 0')")
    error_result = registry.execute("calculator", expression="10 / 0")
    if not error_result.success:
        print(f"      ✓ 错误被正确捕获: {error_result.error}")

    # 尝试调用不存在的工具
    print("\n  尝试执行: nonexistent_tool()")
    error_result = registry.execute("nonexistent_tool")
    if not error_result.success:
        print(f"      ✓ 错误被正确捕获: {error_result.error}")

    # ═══════════════════════════════════════════════════════════════════════
    # 总结
    # ═══════════════════════════════════════════════════════════════════════

    print("\n\n" + "=" * 70)
    print(" ✅ Step 01 完成!")
    print("=" * 70)
    print("""
学到的关键概念：
    1. Tool = name + description + execute
    2. BaseTool 是所有工具的基类
    3. ToolRegistry 统一管理所有工具
    4. ToolResult 统一返回结果格式

下一步：
    继续 Step 02，学习如何管理 Agent 的状态
""")


if __name__ == "__main__":
    main()