AI Agent 工程实践（一）：大模型 API 接入示范

前言

基础能力决定知识体系的上层构建，扎实的底层认知决定后续学习的深度与广度。在进行本实验前，非常建议按照顺序学习以下文章打好基础，上手更快。

人工智能世界观（认知篇）-CSDN博客文章浏览阅读281次，点赞7次，收藏6次。本文系统梳理了人工智能（AI）的基础知识体系，重点解析了大模型（LLM）的核心原理、技术演进及应用边界。主要内容包括： AI基础认知：从规则驱动到数据驱动的范式转变，强调AI=数据+算法+算力的技术本质，区分了弱AI与通用AI（AGI）的能力差异。 技术发展史：回顾AI七十年发展，从符号主义、专家系统到深度学习的五次技术浪潮，重点分析Transformer架构如何推动大模型革命。 大模型原理：详解LLM的三大支柱（参数量/数据量/算力），揭示自回归生成和注意力机制的工作逻辑，对比GPT与BERT的技术路线差https://blog.csdn.net/qq_73252299/article/details/163116481大模型基础（LLM原理篇）-CSDN博客文章浏览阅读239次，点赞7次，收藏5次。本文深入解析了大语言模型(LLM)的技术原理与发展历程，重点阐述了从神经网络基础到Transformer架构革命的关键突破。文章系统性地拆解了大模型训练的完整流程，包括预训练、监督微调(SFT)和人类反馈强化学习(RLHF)三个阶段，揭示了模型如何从海量数据中学习知识并逐步对齐人类意图。通过分析GPT系列的技术演进路线，展现了从简单文本生成到复杂推理能力的涌现过程，并探讨了开源与闭源模型的不同发展策略。文章最后强调理解大模型底层机制的重要性，指出只有穿透"黑箱"表象，才能准确把握这一技术https://blog.csdn.net/qq_73252299/article/details/163215705

AI 应用实践篇------让大模型真正开始工作-CSDN博客文章浏览阅读335次，点赞2次，收藏6次。本文系统介绍了大模型（AI Agent）从入门到实战的全流程应用指南。主要内容包括： 基础入门：介绍了大模型的基本概念、网页聊天交互方式、Prompt工程技巧以及首个AI工作任务的实践方法。 API调用：详细讲解如何通过Python和JavaScript调用大模型API，包括消息结构、流式输出、Token计算及费用优化策略。 Prompt工程：深入剖析Prompt设计方法论，提出结构化框架（RC-T-O-F六要素），涵盖角色设定、上下文注入、任务拆解和Few-shot示例学习等核心技巧。 AI编程助手：对比https://blog.csdn.net/qq_73252299/article/details/163347519第一、第二章都属于理论补充，已经了解的同学可以直接跳到第三章开始实操。

---

在跟随本章实验操作之前，请仔细查看实验用品清单，按需配置实验环境所需资源，部分软件下载需魔法上网环境，请自行准备，实验环境要求：1APIkey+一个应用：

|----------------|------------------------------------------------------------------------------------------|-----------|
| 资源名称 | 地址 | 说明 |
| API服务KEY | https://platform.sec.hn.cn/ | 专业技术大模型平台 |
| Trae IDE/Work | 下载链接 | 字节编码智能体应用 |
| Codex（ChatGPT） | 下载链接 | OpenAI |
| WorkBuddy | 下载链接 | 腾讯专家智能体应用 |
| LobsterAI | 下载链接 | 网易有道龙虾 |
| Aionui | 下载链接 | 桌面办公Agent |

Windows 10+/MacOS12+ ｜Node.js 22+ 、Python3.10+

账户注册

先前往专业技术大模型平台注册一个账号，并且创建一个API KEY：

|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| https://platform.sec.hn.cn/https://platform.sec.hn.cn/ |

平台允许直接使用Github登录，无需注册：

进入后注意两个信息，第一个是API接口URL，复制备用：

第二个是创建API KEY：

创建APIKEY时，注意分组，软件工程开发的选defauit默认分组，运维支持的选opser，网络安全的选择cyper分组，每个分组中的模型不互通！！！

选择好后点击保存更改，即完成，将APIKEY复制出来备用。

模型所属分组，可以在平台的模型广场查看分组：

列出清单

API接口：https://api.sec.hn.cn

APIKEY：sk-cSU7rWXsRDRoynriTHKUPiynh5XzpzCBSgy8FWFLE4RaSdz8

API KEY将在文章发布后失效，请自行创建自己的！！！！！

接口参考文档： 文档说明 - HXSEC AI Platform Docs文档说明 - HXSEC AI Platform Docshttps://docs.sec.hn.cn/

---

一、大模型 API 基础

在 AI Agent 系统中，大模型 API（Large Language Model API）是连接应用程序与人工智能模型能力的核心接口。它类似于传统软件开发中的第三方服务接口，通过标准化的 HTTP 请求方式，使开发者无需自行训练和部署大型模型，即可调用 GPT、Claude、DeepSeek、Gemini 等大语言模型提供的推理能力。简单来说，大模型 API 就是一座连接应用与模型的桥梁。

大模型 API 本质上是一组由模型服务商提供的接口规范，用于完成以下任务：

• 发送用户请求；
• 提供上下文信息；
• 指定调用模型；
• 控制生成参数；
• 获取模型返回结果。

例如，一个简单的聊天请求：

{
  "model": "deepseek-chat",
  "messages": [
    {
      "role": "user",
      "content": "解释一下什么是人工智能"
    }
  ]
}

模型接收到请求后，会根据训练得到的语言能力和当前上下文生成响应：

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "人工智能是一种模拟人类智能能力的技术..."
      }
    }
  ]
}

整个过程类似调用一个远程函数：

answer = AI_Model(prompt)

开发者只需要调用接口，即可获得模型能力。

基本组成

一个完整的大模型 API 请求通常包含以下几个部分：

1. Endpoint（接口地址）

Endpoint 是 API 服务入口，例如：

https://api.sec.hn.cn

不同厂商通常提供不同的 API 地址。例如：

OpenAI
 ↓
api.openai.com

DeepSeek
 ↓
api.deepseek.com

企业自建 Gateway
 ↓
api.sec.hn.cn

---

2. Authentication（身份认证）

大模型 API 通常使用 API Key 进行身份验证。请求示例：

Authorization: Bearer sk-xxxxxxxx

API Key 用于：

• 识别用户身份；
• 控制访问权限；
• 统计调用量；
• 进行费用结算。

在生产环境中，API Key 不应该直接暴露在客户端，而应该通过后端服务代理调用。

---

3. Model（模型选择）

大模型平台通常提供多个模型：例如：

GPT-5
Claude
DeepSeek
Gemini
Qwen

调用时指定：

{
  "model": "xxx-model"
}

不同模型之间存在差异：

类型	特点
通用模型	综合能力强
推理模型	数学、逻辑能力强
编程模型	代码能力强
小模型	成本低、响应快

Agent 系统通常需要根据任务选择不同模型。

---

4. Messages（上下文消息）

现代大模型 API 通常采用消息结构：

[
 {
  "role":"system",
  "content":"你是一个安全专家"
 },
 {
  "role":"user",
  "content":"分析这个漏洞"
 }
]

其中：

system

定义模型行为：例如：

你是一名网络安全分析师

user

用户输入：

分析SQL注入漏洞

assistant

模型历史回复：

该漏洞属于注入类型漏洞

这种设计使模型能够维持多轮上下文。

核心参数

除了输入内容，大模型 API 还提供生成控制参数。

Temperature

控制随机性：

temperature = 0

输出更加稳定。

temperature = 1

输出更加开放。

---

Max Tokens

限制最大输出长度：

{
 "max_tokens":2048
}

用于控制：

• 成本；
• 响应长度；
• 输出范围。

---

Stream（流式输出）

普通请求：

等待模型生成完成
       ↓
一次返回全部结果

流式请求：

模型生成一点
 ↓
立即返回一点
 ↓
继续生成

类似 ChatGPT 打字效果。

与 Agent 的关系

单纯调用 API，只能完成一次问答：

用户
 ↓
LLM API
 ↓
回答

而 Agent 会在 API 基础上增加更多能力：

Agent 通过 API 调用模型，再结合：

• 长期记忆；
• 工具调用；
• 文件处理；
• 数据检索；
• 自动规划；

完成更加复杂的任务。因此，大模型 API 是构建 AI Agent 的基础设施。

---

二、API 接口风格

随着大语言模型生态快速发展，不同模型厂商逐渐形成了各自的 API 调用规范。目前，在 AI Agent 开发领域，主要存在两类具有代表性的接口风格：

• OpenAI Compatible API 风格

• Anthropic Messages API 风格

其中，OpenAI API 凭借较早的生态建设和广泛的开发者基础，逐渐成为事实上的接口兼容标准，大量第三方模型平台、私有化部署服务以及 AI 工具都提供 OpenAI Compatible 接口。

而 Anthropic 则针对 Claude 系列模型设计了独立的 Messages API，在上下文管理、工具调用等方面采用了不同的协议设计。理解两种 API 风格的区别，是构建 AI Agent、开发模型网关以及实现多模型适配的重要基础。

---

OpenAI Compatible API 风格

OpenAI API 最初为 GPT 系列模型服务设计，其核心思想是通过统一的消息结构描述人与模型之间的交互。对专业技术大模型平台API接口进行测试请求，>>接口文档<<：

POST /v1/chat/completions

请求示例：

{
  "model": "gpt-5",
  "messages": [
    {
      "role": "system",
      "content": "你是一名AI助手"
    },
    {
      "role": "user",
      "content": "什么是AI Agent？"
    }
  ]
}

OpenAI 风格使用 messages 数组保存完整上下文，通过不同 role 区分消息来源：

这种设计简单直观，因此被大量框架和工具采用。目前很多模型服务支持类似接口：

OpenAI
   ↓
DeepSeek
   ↓
Qwen
   ↓
Moonshot
   ↓
本地部署模型

只需要修改：

• Base URL

• API Key

• Model Name

即可完成模型替换。

---

Anthropic Messages API 风格

Anthropic Claude API 没有采用 OpenAI 的 Chat Completions 格式，而是设计了自己的 Messages API。

接口：

POST /v1/messages

请求示例：

{
  "model": "claude-sonnet",
  "max_tokens": 2048,
  "system": "你是一名AI助手",
  "messages": [
    {
      "role": "user",
      "content": "什么是AI Agent？"
    }
  ]
}

Anthropic 的核心区别在于：**System Prompt 不作为 messages 中的一部分，而是独立字段。**结构如下：

这种设计将"模型行为控制"和"对话内容"进行了分离。

---

两种 API 接口风格对比

对比项	OpenAI Compatible API	Anthropic API
代表厂商	OpenAI	Anthropic
代表模型	GPT 系列	Claude 系列
API 类型	Chat Completion / Responses	Messages API
请求路径	/v1/chat/completions	/v1/messages
消息主体	messages	messages
System Prompt	role=system	独立 system 参数
用户输入	role=user	role=user
模型回复	role=assistant	role=assistant
最大输出控制	max_tokens	max_tokens
流式输出	stream=true	stream=true
工具调用	tool_calls	tool_use
工具返回	tool message	tool_result
SDK	OpenAI SDK	Anthropic SDK
生态兼容性	非常广泛	Claude 生态为主
常见应用	AI Agent、IDE、API Gateway	Claude Code、Claude Agent

---

Tool Calling 接口差异

在 AI Agent 开发中，工具调用（Tool Calling）是两个接口最大的区别之一。

OpenAI Tool Calling

模型返回：

{
  "tool_calls": [
    {
      "id": "call_xxx",
      "function": {
        "name": "search",
        "arguments": "{}"
      }
    }
  ]
}

工具执行后：

{
  "role": "tool",
  "tool_call_id": "call_xxx",
  "content": "搜索结果"
}

---

Anthropic Tool Use

Claude 返回：

{
  "type": "tool_use",
  "id": "toolu_xxx",
  "name": "search",
  "input": {}
}

工具返回：

{
  "type": "tool_result",
  "tool_use_id": "toolu_xxx",
  "content": "搜索结果"
}

两者实现目标相同：

但协议格式不同，因此 Agent 框架需要进行适配。

---

多模型 Agent 中的 API 适配层

在实际企业级 Agent 系统中，通常不会直接绑定某一种 API，而是在中间增加模型适配层：

适配层负责：

• 请求格式转换；

• 消息结构映射；

• Tool Calling 转换；

• 参数统一；

• Token 统计；

• 错误处理。

例如：

这样，上层 Agent 不需要关心底层模型接口差异。

---

为什么 OpenAI Compatible 成为主流

虽然不同厂商拥有不同 API 规范，但 OpenAI Compatible API 已经形成较强生态优势：大量 AI 工具默认支持 OpenAI 格式。更换模型通常只需要修改：

Base URL
API Key
Model

因此，在现代 AI Agent 工程实践中，常见架构是：

上层采用 OpenAI Compatible 标准降低接入复杂度，底层通过 Adapter 适配不同厂商模型接口。

这也是当前多模型 Agent 平台、AI IDE 和企业级大模型应用的主流设计方式。

---

接下里就进入操作阶段，小白同学请跟着一步一步操作！

---

三、Trae IDE/Work 对接

下载 Trae IDE/Work、并且先登录默认账号，默认账号有免费限额和限速，我们需要先登入后才可以操作设置里的大模型服务商。

点开设置，模型-添加模型：

选择自定义配置：

选择Anthropic格式，填写API请求地址，模型名称和API密钥

模型名称直接在模型广场点复制按钮即可：

填写完成后提交：

在首页中的模型切换即可使用：

测试输入：hello，正常输出即可：

Work的对接工作成功。IDE的对接工作与Work类似，同样在设置-模型-自定义模型：

依次填入即可：

---

四、Codex 对接

需要预先安装CC Switch或openCodex，这里以OpenCodex为例：系统环境中需要预先安装Node.js环境，然后打开终端执行安装命令：

npm install -g @bitkyc08/opencodex

较新的 npm 可能会拦截 bun 的 postinstall 脚本（npm warn install-scripts ... blocked because they are not covered by allowScripts），导致捆绑的 Bun 运行时未能就绪。请允许 bun 脚本后重新安装。注意 npm 警告给出的缩写命令 缺少包名，会把当前目录重新安装进去，请始终显式写上包名：

npm install -g --allow-scripts=bun @bitkyc08/opencodex
sudo npm install -g --allow-scripts=bun @bitkyc08/opencodex

安装完成后运行启动命令：

ocx start

浏览器访问：http://localhost:10100/#dashboard

点击框选处进入，确保两项启动项都已确认安装成功，确保服务商可以正常注入Codex的模型列表

点击左侧边栏提供方-然后新建提供方：

弹出的模态框中，点击右下角添加自定义服务商：

填写对应的API URL、API请求风格、APIKey后点击左下角添加提供方：

如果报错：baseUrl hostname api.sec.hn.cn resolves to a benchmark address (198.18.0.41); set allowPrivateNetwork:true only for intentionally local/self-hosted providers，可能是开了代理软件，可以关闭或勾选允许本地/私有网络的复选框即可。点击添加后，将自动从服务商拉取可用模型列表：

重启Codex，在右下角模型切换列表即可看到模型成功注入：

测试可用性：

成功。

---

五、WorkBuddy 对接

下载并安装WoekBuddy，先登录，然后点头像处，然后点设置

点模型，添加模型

提供商选择自定义：

这里需要注意，WorkBuddy仅支持OpenAI格式接入，所以需要在API地址后面加入/v1路径：

思考模式这些可以选择性打开，确认后，点击保存测试：

可用，接入正常。

---

六、LobsterAI 对接

下载并安装LobsterAI，先登录，确保软件页面正常显示，然后在软件窗体左下角点击设置：

依次填入API KEY，API URL，选择接口模式，添加模型：

支持图像输出的记得勾选，模型上下文支持1M的要选择，保存后会自动重启软件，测试可用性：

对接成功。

---

七、Aionui 对接

下载并安装Aionui，点击软件窗体左下角的设置，进入设置选项：

选择模型，添加模型：

点手动安装，然后填入API接口URL和apikey，会自动读取可用模型：

点击确定即可，此软件有多Agent协作的能力，我们进行测试：

成功至此，API接口对接的教程涵盖目前主要使用的Agent场景。