Agent 开发入门（一）：从一次 API 调用开始

别急着学框架，先用百炼平台搞懂一次大模型 API 调用里每个参数在干什么。

你想学 AI Agent 开发，网上一搜全是 LangChain、AutoGPT、各种框架。

先别急。

所有 Agent 框架的底层，都是在调大模型的 API。框架帮你封装了很多东西，但如果你不理解底层那次 API 调用在干什么，后面遇到问题就是黑盒。

这篇文章，我们就做一件事：用阿里云百炼平台，搞懂一次大模型 API 调用的每个参数。

为什么选百炼

如果你对各家大模型 API 格式的历史和差异感兴趣，可以看我之前写的「大模型 API 格式的前世今生」。本篇专注实操，直接上手调用。

百炼是阿里云的大模型服务平台，选它做入门示例有几个原因：

• 国内直连，不用折腾网络
• 兼容 OpenAI 格式，学会了到哪都能用
• 通义千问系列模型免费额度够用
• 注册就能用，不需要企业认证

准备工作

1. 打开 百炼控制台，用阿里云账号登录
2. 进入「API-KEY 管理」，创建一个 API Key
3. 记下这个 Key，后面要用

最简单的一次调用

作为 Java 开发者，我们用 JDK 自带的 HttpClient，零依赖：

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ChatDemo {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();

        String requestBody = """
                {
                    "model": "qwen-plus",
                    "messages": [
                        {"role": "user", "content": "什么是 AI Agent？用一句话解释。"}
                    ]
                }
                """;

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(
                    "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions"))
                .header("Authorization", "Bearer YOUR_BAILIAN_API_KEY")
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                .build();

        HttpResponse<String> response = client.send(request,
                HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

就这么几行，你已经完成了一次大模型调用。没有任何第三方依赖，JDK 17+ 自带的 HttpClient 就够了。

注意百炼的兼容模式地址：dashscope.aliyuncs.com/compatible-mode/v1，加上 /compatible-mode 就走 OpenAI 兼容格式。

拆解：messages 是什么

messages 是你和模型对话的完整记录，它是一个数组，每条消息有两个关键字段：

• role：谁说的
• content：说了什么

role 有三种：

role	含义	你可以理解为
system	系统指令	给模型的"人设说明书"
user	用户输入	你说的话
assistant	模型回复	模型说的话

一个更完整的例子：

"messages": [
    {"role": "system", "content": "你是一个资深 Java 开发者，回答要简洁实用。"},
    {"role": "user", "content": "Spring Boot 3 和 2 的最大区别是什么？"}
]

system 消息就像是你在模型开始工作前，给它贴了一张便签纸。它会影响模型后续所有回复的风格和行为。

这里有个关键认知：模型没有记忆。每次调用都是独立的。你觉得它"记住"了上文，其实是因为你把之前的对话全部塞进了 messages 数组里重新发了一遍。

拆解：model 怎么选

百炼平台上可用的通义千问模型：

模型	特点	适合场景
qwen-turbo	快、便宜	简单对话、分类、提取
qwen-plus	均衡	日常开发、代码生成
qwen-max	最强	复杂推理、长文写作

入门阶段用 qwen-plus 就够了，效果和速度都不错。

因为百炼兼容 OpenAI 格式，如果以后想换 DeepSeek 或其他模型，只需要改地址和模型名，代码结构完全不变：

// 百炼 + 通义千问
.uri(URI.create("https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions"))
// model: "qwen-plus"

// DeepSeek
.uri(URI.create("https://api.deepseek.com/v1/chat/completions"))
// model: "deepseek-chat"

这就是 OpenAI 兼容格式的好处——学一次，到处用。

拆解：temperature 和 top_p

这两个参数控制模型回复的"随机性"：

"temperature": 0.7,
"top_p": 1.0

简单理解：

• temperature = 0：每次回答几乎一样，适合写代码、做判断
• temperature = 1：正常发挥，适合日常对话
• temperature > 1：更有创意但可能跑偏，适合头脑风暴

top_p 的效果类似，一般二选一调就行，不用同时改。

实用建议：做 Agent 开发时，大部分场景用 temperature=0 或 0.1。因为你希望 Agent 的行为稳定可预测，不是让它每次给你不同的花活。

拆解：max_tokens

"max_tokens": 2000

这个参数限制模型单次回复的最大长度。注意几点：

• 它限制的是输出，不是输入
• 1 个 token ≈ 1.5 个中文字 或 0.75 个英文单词
• 不设的话模型会用默认上限
• 设太小会导致回复被截断

拆解：stream

"stream": true

设为 true 后，模型会一个字一个字地返回，而不是等全部生成完再返回。就像你在 ChatGPT 里看到的打字效果。

做 Agent 时一般不需要 stream，因为你要等完整结果才能做下一步判断。但做面向用户的聊天界面时，stream 体验好很多。

完整参数一览

把上面的参数放在一起，一个完整的 Java 示例：

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ChatDemo {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();

        String requestBody = """
                {
                    "model": "qwen-plus",
                    "messages": [
                        {"role": "system", "content": "你是一个有用的助手。"},
                        {"role": "user", "content": "帮我解释什么是 AI Agent。"}
                    ],
                    "temperature": 0,
                    "max_tokens": 2000,
                    "stream": false
                }
                """;

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(
                    "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions"))
                .header("Authorization", "Bearer YOUR_BAILIAN_API_KEY")
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                .build();

        HttpResponse<String> response = client.send(request,
                HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

直接复制就能跑。JDK 17+ 支持文本块语法，写 JSON 很舒服。如果你还在用 JDK 11，把文本块换成字符串拼接就行。

返回结果长什么样

API 返回的 JSON 结构：

{
  "id": "chatcmpl-xxx",
  "model": "qwen-plus",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "AI Agent 是一个能够自主感知环境、做出决策并执行行动的智能程序..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 80,
    "total_tokens": 105
  }
}

几个值得关注的字段：

• choices[0].message.content：模型的回复内容
• finish_reason：stop 表示正常结束，length 表示被 max_tokens 截断了
• usage：token 用量，直接关系到你的账单

这和 Agent 有什么关系？

你可能会问：这不就是调了个 API 吗，Agent 在哪？

Agent 的本质就是：让模型的输出驱动下一步行动。

普通调用：你问 → 模型答 → 结束。

Agent 调用：你问 → 模型判断要做什么 → 调用工具 → 拿到结果 → 模型再判断 → 继续或结束。

而这个"调用工具"的能力，就是下一篇要讲的 Function Calling。

但不管 Agent 多复杂，底层都是我们今天看到的这个 API 调用。messages 会越来越长，参数会多几个，但核心结构不变。

动手试试

1. 去 百炼控制台 注册，创建 API Key
2. 把上面的完整示例跑一遍
3. 试着改 system 消息，观察回复风格的变化
4. 把 temperature 从 0 调到 1.5，感受差异
5. 把 model 从 qwen-plus 换成 qwen-turbo，对比速度和效果

下一篇，我们给模型装上"手"——Function Calling，让它不只是说，还能做。

---

本文 API 格式基于百炼 OpenAI 兼容接口文档，如有变动请以官方最新文档为准。

---

觉得有用的话点个收藏，后续系列持续更新。