> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

本文档旨在帮助你快速集成扣子罗盘 Java SDK，实现从 SDK 初始化、Trace 数据上报到 Prompt 调用的完整流程。
## 环境准备 {#1af0f241}
### 系统要求 {#338a3ff9}
在开始集成 SDK 前，请确保开发环境满足以下要求：

* **Java Development Kit**: 1.8 或更高版本。
* **构建工具**: [Maven](https://maven.apache.org/) 3.6 或更高版本。

### 鉴权配置 {#697affc6}
使用扣子罗盘 Java SDK 前需完成鉴权配置。详细说明请参考 [SDK 鉴权](/cozeloop/authentication-for-sdk)。
SDK 支持以下两种鉴权方式：
#### 方式一：Personal Access Token (PAT) {#fe473ae5}
适用于本地开发与测试环境。通过环境变量配置：
```Bash
export COZELOOP_WORKSPACE_ID="your_workspace_id"
export COZELOOP_API_TOKEN="your_pat_token"
```


* **COZELOOP_WORKSPACE_ID**: 目标工作空间 ID。
* **COZELOOP_API_TOKEN**: 个人访问令牌。

#### 方式二：OAuth JWT (推荐) {#8828b680}
适用于生产环境，提供更高的安全性。需配置以下环境变量：
```Bash
export COZELOOP_WORKSPACE_ID="your_workspace_id"
export COZELOOP_JWT_OAUTH_CLIENT_ID="your_client_id"
export COZELOOP_JWT_OAUTH_PRIVATE_KEY="your_private_key"
export COZELOOP_JWT_OAUTH_PUBLIC_KEY_ID="your_public_key_id"
```

## SDK 安装 {#cb5e87e3}
根据项目类型选择对应的 Maven 依赖。
:::tip
**版本提示**：下面示例代码中使用的 SDK 版本为 0.1.6。请查阅 Maven Central 获取最新版本号：https://mvnrepository.com/artifact/com.coze/cozeloop-java/versions。
:::
### 标准 Java 项目 {#183838e1}
对于非 Spring Boot 项目，引入 `cozeloop-core`：
```XML
<dependency>
    <groupId>com.coze</groupId>
    <artifactId>cozeloop-core</artifactId>
    <version>0.1.6</version>
</dependency>
```

### Spring Boot 项目 {#a9d4f0f8}
推荐使用 Starter 简化配置：
```XML
<dependency>
    <groupId>com.coze</groupId>
    <artifactId>cozeloop-spring-boot-starter</artifactId>
    <version>0.1.6</version>
</dependency>
```

## 初始化 SDK {#5748f9d8}
### 非 Spring Boot 环境 {#d3dbd1f3}
使用 `CozeLoopClientBuilder` 构建实例。若已配置环境变量，无需手动传入凭证。
```Java
import com.coze.loop.client.CozeLoopClient;
import com.coze.loop.client.CozeLoopClientBuilder;

public class Application {
    public static void main(String[] args) {
        // 推荐：使用 try-with-resources 自动关闭 client，确保 Trace 数据完整上报
        try (CozeLoopClient client = new CozeLoopClientBuilder()
                .serviceName("my-java-app") // 设置当前服务名称，便于在平台区分数据来源
                .build()) {
            
            System.out.println("SDK 初始化成功");
            // 执行业务逻辑...
            
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

### Spring Boot 环境 {#09648ae0}
使用 `cozeloop-spring-boot-starter` 时，SDK 将自动注入 `CozeLoopClient` Bean。

1. **启用自动配置**

在启动类添加 `@Import(CozeLoopAutoConfiguration.class)` 注解。
```Java
import com.coze.loop.spring.autoconfigure.CozeLoopAutoConfiguration;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Import;

@SpringBootApplication
@Import(CozeLoopAutoConfiguration.class)
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
```


2. **配置文件设置 (可选)**

在 `application.yml` 中配置服务名称等信息。
```YAML
cozeloop:
  # (可选) 如果未设置环境变量，可在此处指定
  # workspace-id: your_workspace_id
  # auth:
  #   token: your_pat_token   # pat token 和 jwt 二选一即可
  #   jwt:
  #     clientId: your_client_id
  #     privateKey: your_private_key
  #     publicKeyId: your_public_key
  service-name: my-spring-boot-app
  trace:
    enabled: true
```

## Trace 上报 {#b20e6cdc}
通过 Span 追踪代码执行链路，上报数据至扣子罗盘，实现全链路可观测性。
:::tip
**最佳实践**：始终使用 **`try-with-resources`** 管理 Span，确保在异常发生时 Span 也能正确关闭并上报。
:::
### 上报 Root Span {#09d818f2}
Root Span 是调用链路的起点，通常对应一个完整的请求处理过程。
```Java
import com.coze.loop.client.CozeLoopClient;
import com.coze.loop.trace.CozeLoopSpan;
import com.coze.loop.client.CozeLoopClientBuilder;

// client 初始化
CozeLoopClient client = new CozeLoopClientBuilder().build();

try (CozeLoopSpan rootSpan = client.startSpan("process_user_request", "custom")) {
    rootSpan.setTag("user.id", "user-123");
    rootSpan.setInput("User query: tell me a joke");

    // 执行业务逻辑...

    rootSpan.setOutput("Why don't scientists trust atoms? Because they make up everything!");
    rootSpan.setStatusCode(0); // 0: 成功, 1: 失败
} catch (Exception e) {
    // 异常会自动被 SDK 捕获并记录
}
```

### 上报自定义 Span {#34da9db3}
在 Root Span 内部创建子 Span，用于追踪细粒度的操作（如数据库查询、外部 API 调用）。
```Java
try (CozeLoopSpan rootSpan = client.startSpan("main_process", "custom")) {
    
    // 创建子 Span，自动关联父级 Span
    try (CozeLoopSpan childSpan = client.startSpan("database_query", "db")) {
        childSpan.setTag("db.statement", "SELECT * FROM users;");
        // 执行数据库查询...
    }
}
```

### 上报 Model Span {#8e3c53c1}
调用 LLM 时，使用 `model` 类型的 Span 记录输入输出和 Token 消耗。
```Java
import com.coze.loop.spec.tracespec.*;
import java.util.Collections;

try (CozeLoopSpan modelSpan = client.startSpan("llm_call_openai", "model")) {
    // 1. 设置输入与元数据
    ModelInput input = new ModelInput();
    input.setMessages(Collections.singletonList(new ModelMessage("user", "上海天气")));
    modelSpan.setInput(input);
    modelSpan.setModelProvider("openai");
    modelSpan.setModelName("gpt-4");

    // 2. 执行 LLM 调用 (伪代码)
    // Response resp = openAiClient.chat(...)
    
    // 3. 记录输出与 Token
    ModelOutput output = new ModelOutput();
    output.setChoices(Collections.singletonList(
        new ModelChoice(new ModelMessage("assistant", "晴，28度"), "stop", 0L)
    ));
    modelSpan.setOutput(output);
    modelSpan.setInputTokens(10);
    modelSpan.setOutputTokens(20);
}
```

## Prompt 管理与执行 {#ebfcde78}
使用 SDK 拉取并执行在扣子罗盘平台定义的 Prompt。
### 拉取并格式化 Prompt {#e3838252}
在使用 SDK 拉取 Prompt 前，需要在扣子罗盘的 Prompt 开发页面获取 Prompt Key 和版本号。
![Image=2826x669](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/affe20efa44c471bb1d901e4e9bdb8af~tplv-goo7wpa0wc-image.image)
动态填充 Prompt 变量，获取格式化后的消息内容。
```Java
import com.coze.loop.client.CozeLoopClient;
import com.coze.loop.client.CozeLoopClientBuilder;
import com.coze.loop.entity.Message;
import com.coze.loop.entity.Prompt;
import com.coze.loop.prompt.GetPromptParam;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

CozeLoopClient client = new CozeLoopClientBuilder().build();

try {
    // 1. 获取 Prompt 对象
    Prompt prompt = client.getPrompt(
        GetPromptParam.builder()
            .promptKey("your_prompt_key")
            .build()
    );

    if (prompt != null) {
        // 2. 准备变量并格式化
        Map variables = new HashMap<>();
        variables.put("query", "什么是机器学习？");

        List formattedMessages = client.formatPrompt(prompt, variables);
        
        // 3. 使用格式化后的消息（如用于日志打印或调试）
        formattedMessages.forEach(msg -> 
            System.out.println(msg.getRole() + ": " + msg.getContent())
        );
    }
} catch (Exception e) {
    e.printStackTrace();
}
```

### 执行 Prompt {#58c36aae}
直接调用 SDK 执行 Prompt，支持流式与非流式。流式调用的详情请参阅 [调用 Prompt](/cozeloop/ptaas-for-java-sdk)。
```Java
// 非流式调用示例
try (CozeLoopClient client = new CozeLoopClientBuilder().build()) {
  Map variables = new HashMap<>();
  variables.put("query", "你好");

  ExecuteParam param = ExecuteParam.builder()
      .promptKey("yourPromptKey")
      .variableVals(variables)
      .build();

  ExecuteResult result = client.execute(param);
  
  if (result.getMessage() != null) {
    System.out.println(result.getMessage().getContent());
  }
}
```

## 示例资源 {#1eeaeefe}
更多完整示例代码，请访问 GitHub 仓库：
<!-- @cols-width: 121,500,273 -->
| | | | \
|**模块** |**示例文件** |**说明** |
|---|---|---|
| | | | \
|授权 |https://github.com/coze-dev/cozeloop-java/tree/main/examples/src/main/java/init/pat |PAT 鉴权示例 |
|^^| | | \
| |https://github.com/coze-dev/cozeloop-java/tree/main/examples/src/main/java/init/oauth_jwt |OAuth JWT 鉴权示例 |\
| | | |
| | | | \
|环境集成 |https://github.com/coze-dev/cozeloop-examples/tree/main/java/native/non_spring_boot |Java 原生环境 |\
| | | |
| | | | \
| |https://github.com/coze-dev/cozeloop-examples/tree/main/java/native/spring_boot |Spring Boot 集成 |
| | | | \
|Prompt |\
| |https://github.com/coze-dev/cozeloop-java/tree/main/examples/src/main/java/prompt/prompt_hub |Prompt 拉取与管理 |
|^^| | | \
| |https://github.com/coze-dev/cozeloop-java/tree/main/examples/src/main/java/prompt/prompt_hub_jinja |Jinja 模板支持 |
|^^| | | \
| |https://github.com/coze-dev/cozeloop-java/tree/main/examples/src/main/java/prompt/prompt_execute |Prompt 执行 |
| | | | \
|Trace |https://github.com/coze-dev/cozeloop-java/tree/main/examples/src/main/java/trace/simple |基础 Trace 上报 |
|^^| | | \
| |https://github.com/coze-dev/cozeloop-java/tree/main/examples/src/main/java/trace/parent_child |父子 Span 关联 |
|^^| | | \
| |https://github.com/coze-dev/cozeloop-java/tree/main/examples/src/main/java/trace/annotation |注解式 Trace |
|^^| | | \
| |https://github.com/coze-dev/cozeloop-java/tree/main/examples/src/main/java/trace/transfer_between_services |跨服务 Trace 透传 |
| | | | \
|其他 |https://github.com/coze-dev/cozeloop-java/tree/main/examples/src/main/java/init/error |异常处理示例 |