---
title: "harness - 进一步扩展定制参考"
---

`solon-ai-harness` 提供了灵活的扩展能力，允许开发者通过代码动态定制 Web API 接入、业务工具集成以及系统提示词。

### 1、主代理（Agent）定制扩展


* 动态添加 Web API (Open API) 数据源

除了静态配置外，您可以通过代码动态注册外部 API 接口文档（如 Swagger/OpenAPI），使 Agent 具备调用外部业务系统的能力。


```java
HarnessEngine engine = HarnessEngine.of(...)
        .sessionProvider(sessionProvider)
        .build();
        
// 注册业务 API 数据源：以文档地址（docUrl）为唯一标识
engine.addApiServer(new ApiSource().then(s->{
            s.setDocUrl("http://xx.xx.xx/doc");
            s.setApiBaseUrl("http://xx.xx.xx/");
        }));
```

* 注册自定义业务工具 (Tools)

如果现有的 API 无法满足逻辑需求，可以直接将 Java 编写的业务类注册为 Agent 工具，实现复杂的计算或数据库操作。

```java
HarnessEngine engine = HarnessEngine.of(...)
                .sessionProvider(sessionProvider)
                .extensionAdd((agentName, agentBuilder) -> {
                    // 注册默认工具实例
                    agentBuilder.defaultToolAdd(new BizTool());
                })
                .build();
```

* 灵活配置系统提示词 (System Prompt)

Agent 的行为准则通常由 `{workspace}/{harnessHome}/AGENTS.md` 文件定义。在没有配置文件或需要动态生成提示词的场景下，可以使用代码进行覆盖：

```java
HarnessEngine engine = HarnessEngine.of(...)
                .sessionProvider(sessionProvider)
                .extensionAdd((agentName, agentBuilder) -> {
                    if("main".equals(agentName)) {
                        // 动态设置系统提示词逻辑
                        agentBuilder.systemPrompt(context -> "你是一个专业的业务助手...");
                    }
                })
                .build();
```

也可以在运行时通过 `setSystemPrompt` 动态修改：

```java
engine.setSystemPrompt("新的系统提示词");
```

* 配置缓存控制 (CacheControl)

对于支持 Prompt Caching 的模型（如 Anthropic Claude），可以配置 `CacheControl` 以减少重复计算：

```java
HarnessEngine engine = HarnessEngine.of(...)
        .sessionProvider(sessionProvider)
        .cacheControl(CacheControl.of(...))
        .build();

// 运行时也可动态修改
engine.setCacheControl(CacheControl.of(...));
```

* 运行时动态管理扩展

扩展可以在构建期静态添加，也可以在运行时动态增删：

```java
engine.addExtension((agentName, agentBuilder) -> {
    // 新增的扩展逻辑
});

engine.removeExtension(extension);  // 移除指定扩展（触发主代理重建）
```


### 2、子代理（Subagent）定制扩展

子代理有两种使用场景：

* 1）被主代理调度时，不可定制，只能通过 `{workspace}/{harnessHome}/agents/xxx.md` 定义。
* 2）使用代码调度时（可以进一步定制）。

```java
AgentSession session = engine.getSession("default");

//动态定义智能体
AgentDefinition definition = new AgentDefinition();
definition.setSystemPrompt("xxx"); //系统提示词
definition.getMetadata().addTools(ToolName.TOOL_BASH); //工具权限

ReActAgent subagent = engine.createSubagent(definition).defaultToolAdd(new OrderTool()).build();
subagent.prompt(prompt)
        .session(session) //没有，则为临时会话
        .options(o -> {
            //按需，动态指定工作区（没有，则为默认工作区）
            o.toolContextPut(HarnessEngine.ATTR_CWD, "xxx");
        })
        .call();
```

`engine.createSubagent(definition)` 返回的是 `ReActAgent.Builder`，仍可自由定制。

### 3、通过 AgentManager 管理子代理

```java
// 获取内置子代理定义
AgentDefinition bashDef = engine.getAgentManager().getAgent("bash");

// 构建子代理并执行
ReActAgent bashAgent = bashDef.builder(engine).build();
bashAgent.prompt("列出当前目录所有 Java 文件")
        .session(session)
        .call();

// 获取所有可用子代理（不含隐藏的）
Collection<AgentDefinition> agents = engine.getAgentManager().getAgents();

// 动态添加子代理定义
engine.getAgentManager().addAgent(customDefinition);
engine.getAgentManager().addAgentIfAbsent(customDefinition); // 仅在不存在时添加
```