侦察兵Research Scout

任务简报Brief

学习目标Learning goals

• 用 FunctionTool / @Tool 暴露 search_notes 与 save_brief。

  Expose search_notes and save_brief with FunctionTool / @Tool.

• 让模型在一次 ReAct 循环里连续调用两个工具。

  Let the model call two tools in one ReAct loop.

• 用 Pydantic / record 接收结构化结果，并验证字段。

  Receive and validate structured output with Pydantic / a record.

• 确保工具真的产生了副作用文件，而不是只返回一句话。

  Ensure the tool actually writes its artifact instead of only returning text.

核心概念Core concepts

双轨实现Build it twice

先完整跑通一条轨道，再切换重来。两条轨道写出同一种产物，方便直接对照行为。Run one track end to end, then switch and repeat. Both tracks write the same artifact so you can compare behavior directly.

from agentscope.tool import FunctionTool, Toolkit
from common.tools import save_brief, search_notes

toolkit = Toolkit(
    tools=[
        FunctionTool(search_notes, permission=LAB_ALLOW, is_read_only=True),
        FunctionTool(save_brief, permission=LAB_ALLOW),
    ],
)

from pydantic import BaseModel, Field

class ResearchBrief(BaseModel):
    title: str = Field(description="Short title of the brief")
    findings: list[str] = Field(description="Concrete findings")
    confidence: float = Field(ge=0, le=1)

reply = await agent.reply(
    UserMsg("user", "Research ReAct guardrails and save a brief."),
    structured_schema=ResearchBrief,
)
print(reply.structured_output)  # dict, already validated

python lab.py check m1
cat work/m1/brief.json

# 期望看到
# PASS CODE: AS-M1-K2VD

python lab.py check m1

public final class BriefTools {
  @Tool(name = "search_notes", readOnly = true,
        description = "Search the local research corpus.")
  public String searchNotes(
      @ToolParam(name = "query") String query,
      @ToolParam(name = "limit", required = false) Integer limit) { ... }

  @Tool(name = "save_brief", description = "Save a research brief.")
  public String saveBrief(
      @ToolParam(name = "title") String title,
      @ToolParam(name = "findings") List<String> findings,
      @ToolParam(name = "confidence", required = false) Double confidence) { ... }
}

Toolkit toolkit = new Toolkit();
toolkit.registerTool(new BriefTools());

ReActAgent agent = ReActAgent.builder()
        .name("scout").sysPrompt("Search, save a brief, return typed output.")
        .model(model).toolkit(toolkit).maxIters(6)
        .permissionContext(PermissionContextState.builder()
                .mode(PermissionMode.BYPASS).build())
        .build();

Msg reply = agent.call(List.of(LabSupport.user("Research ReAct guardrails.")),
        ResearchBrief.class, context).block();

cd lab/java
mvn -q -o compile exec:java -Dexec.args="check m1"

# 期望看到
# PASS CODE: AS-M1-K2VD

cd lab/java && mvn -q -o compile exec:java -Dexec.args="check m1"

Python ↔ Java 差异Python ↔ Java differences

• Python 从 docstring/类型注解推导 schema；Java 用 @Tool / @ToolParam 显式描述。两边最终都变成模型可读的 JSON Schema。

  Python derives schema from docstrings/type hints; Java uses @Tool / @ToolParam. Both end up as model-readable JSON Schema.

• Python 返回 reply.structured_output 字典；Java 从 Msg.getMetadata().get("_structured_output") 取 Map，再转换成 record。

  Python returns a structured_output dict; Java reads _structured_output from Msg metadata and converts it to a record.

• Java 的结构化输出依赖内置工具 generate_response；调试时如果模型没调用它，回复会是普通文本。

  Java structured output relies on the built-in generate_response tool; if the model skips it, you get plain text.

常见坑Pitfalls

1. 工具参数类型不是 JSON 可序列化的：例如自定义对象没有无参构造/序列化器。保持参数为字符串、数字、布尔、列表和简单 Map。

   Non-JSON-serializable tool parameters break schema generation. Keep parameters to strings, numbers, booleans, lists and simple maps.

2. 只检查文本回复：工具可能返回 Error 但模型仍然礼貌地回答。必须读取 ToolResultBlock 的状态与内容。

   Checking only reply text: a tool may return an Error while the model still answers politely. Inspect the ToolResultBlock state and content.

3. 把 confidence 当成模型自觉：它只是字段。生产环境要用外部校验、置信度阈值或人工复核。

   Treating confidence as self-awareness: it is only a field. Production needs external validation, thresholds or human review.

领取通行码Claim your pass code

先运行当前轨道的 check。CLI 会打印 PASS CODE、XP 与徽章。粘贴到这里；同一关在每条轨道可各领取一次。Run the check for the current track. The CLI prints PASS CODE plus the exact XP and badge. Paste it here; the same mission can be claimed once on each track.

费曼复述Feynman recall

合上教程，用自己的话讲清机制。关键点覆盖 65%、篇幅 20%、结构 15%；60 分通过并一次性获得 20 XP。Explain the mechanism without looking. Coverage 65%, length 20%, structure 15%; 60 passes and earns +20 XP once.

间隔复习Spaced review

首次领取后会在明天安排复习。按真实感受评分，下一次间隔会自适应。After the first claim a review is scheduled for tomorrow. Rate how it felt; the next interval adapts.