定义工具

自定义工具是普通 Java 对象，方法上使用 agentscope 的 @Tool 和 @ToolParam 注解：

import io.agentscope.core.tool.Tool;
import io.agentscope.core.tool.ToolParam;

public class OrderTool {

    @Tool(name = "query_order_status", description = "Query order status by order number")
    public String query(@ToolParam(name = "orderNo") String orderNo) {
        return "订单 " + orderNo + " 正在处理中";
    }
}

注册工具

在 Agent 组件中覆写 tools() 方法：

@Override
protected List<Object> tools() {
    return List.of(new OrderTool());
}

在工具中访问上下文

如果工具需要访问当前 Slot、workspace 或 conversation 信息，不要在构造工具时捕获 ctx() 的返回值。推荐做法：

方式 1：工具写成组件内部类

@Component("orderAgent")
public class OrderAgentCmp extends ReActAgentComponent {

    // ... model(), systemPrompt(), userPrompt() ...

    @Override
    protected List<Object> tools() {
        return List.of(new OrderToolInner());
    }

    // 内部类可以直接访问外部类的方法
    private class OrderToolInner {
        @Tool(name = "query_order", description = "查询订单状态")
        public String query(@ToolParam(name = "orderNo") String orderNo) {
            // 通过外部类间接访问 ctx()
            Slot slot = ctx().getSlot();
            // 业务逻辑...
            return "订单 " + orderNo + " 正在处理中";
        }
    }
}

方式 2：组件提供公开代理方法

@Component("orderAgent")
public class OrderAgentCmp extends ReActAgentComponent {

    // 供工具调用的代理方法
    public Slot getCurrentSlot() {
        return ctx().getSlot();
    }

    @Override
    protected List<Object> tools() {
        return List.of(new OrderTool(this));
    }
}

public class OrderTool {
    private final OrderAgentCmp agent;

    public OrderTool(OrderAgentCmp agent) {
        this.agent = agent;
    }

    @Tool(name = "query_order", description = "查询订单状态")
    public String query(@ToolParam(name = "orderNo") String orderNo) {
        Slot slot = agent.getCurrentSlot();
        return "订单 " + orderNo + " 正在处理中";
    }
}

不要在缓存对象中保存 ctx() 引用

如果工具、Hook 或 Model 会被缓存并跨多次 invocation 复用，不要在其中保存某次调用的 ReActAgentContext 引用。应保存组件实例，运行时通过组件间接调用 ctx() 获取当次上下文。