AgentKit添加自定义LLM模型：完整操作教程与适配指南

算力阿峰

2026-9-11

[1] 一句话结论

本指南将手把手教你在AgentKit中快速接入自定义新LLM模型，附避坑要点。

[2] 适用场景与不适用场景

适用场景

适合已经使用AgentKit开发智能体，需要新增接入未在原生支持列表中的开源/私有大模型的场景
适合需要在多个LLM之间无缝切换、统一调用接口的多模型智能体开发场景
适合日均API调用量在1万次以上，需要对模型调用逻辑做统一封装的企业级开发场景

不适用场景

如果你的场景仅需要调用原生支持的29款主流模型，不需要额外自定义适配，建议直接使用原生配置，无需走自定义接入流程
如果你的场景是单模型轻量Demo开发，无多模型切换需求，建议直接调用对应模型原生API，无需引入AgentKit框架
如果你的模型没有标准HTTP调用接口，无法通过网络请求访问，建议先完成模型服务化部署后再考虑接入

[3] 前置准备

Node.js 16+ 或 Python 3.8+ 开发环境
已开通火山引擎AgentKit权限，获取到项目访问密钥
AgentKit SDK版本：JavaScript版v1.2.0+ / Python版v0.7.0+
已拿到待接入LLM的API密钥、接口文档、请求/响应格式规范
预计耗时：30分钟

[4] 分步实现

步骤1：安装对应版本AgentKit SDK

步骤说明：首先我们要安装匹配版本的SDK，版本不匹配会导致自定义Provider接口不兼容，无法注册新模型。
代码/命令：

# JavaScript版本安装
npm install @volcengine/agentkit@1.2.0 --save

# Python版本安装
pip install ni.agentkit==0.7.0

预期结果：终端输出安装成功日志，无报错信息。

⚠️ 常见错误：安装时出现依赖冲突，提示找不到对应版本包。
原因：要么是源配置错误，要么是指定的版本号不对，部分旧版本镜像没有同步最新的SDK包。
解决方法：切换到npm官方源或者火山引擎npm镜像源，核对版本号后重新安装。

步骤2：配置新LLM模型的Provider信息

步骤说明：这一步是把新模型的接口信息注册到AgentKit的Provider管理中心，AgentKit靠Provider来统一封装不同模型的调用逻辑，跳过这一步无法识别你要接入的新模型。
代码/命令：

const { AgentKit, ModelProvider } = require('@volcengine/agentkit');

// 注册自定义模型Provider
const customLLMProvider = new ModelProvider({
  name: 'my_custom_llm', // 自定义provider名称，后续调用时用这个标识
  endpoint: 'https://your-custom-llm-api.com/v1/chat/completions', // 模型接口地址
  apiKey: 'YOUR_CUSTOM_LLM_API_KEY', // 替换为你的模型API密钥
  // 参数映射规则，把AgentKit的统一参数转为模型需要的参数
  paramsMapping: {
    temperature: 'temperature',
    max_tokens: 'max_output_tokens',
    messages: 'messages'
  },
  // 响应解析规则，把模型返回的内容转为AgentKit统一格式
  responseParser: (resp) => {
    return {
      content: resp.choices[0].message.content,
      usage: resp.usage
    }
  }
})

const agentkit = new AgentKit({
  providers: [customLLMProvider] // 把自定义provider加入实例
})

预期结果：配置代码无语法报错，AgentKit实例初始化成功。

⚠️ 常见错误：调用时提示"provider not found"。
原因：要么是注册时的provider名称和调用时指定的名称不一致，要么是没有把自定义provider加入AgentKit实例的providers数组里。
解决方法：核对两个名称完全一致，确认providers数组已经包含你定义的provider实例。

步骤3：编写模型调用测试代码

步骤说明：配置完Provider之后，我们要先写一个简单的调用逻辑，验证基础请求是否能正常通，确认参数映射和响应解析逻辑是正确的。
代码/命令：

async function testCustomLLM() {
  const response = await agentkit.createChat({
    provider: 'my_custom_llm', // 指定刚才注册的自定义provider
    messages: [
      { role: 'user', content: '你好，请介绍一下你自己' }
    ],
    temperature: 0.7,
    max_tokens: 1000
  })
  console.log('模型返回结果：', response.content)
  console.log('token消耗：', response.usage)
}

testCustomLLM()

预期结果：控制台打印出模型返回的回答内容和token使用量。

步骤4：配置全局默认模型（可选）

步骤说明：如果你后续大多数调用都要使用这个新接入的模型，可以把它设为全局默认，这样每次调用就不用重复指定provider参数了，减少冗余代码。
代码/命令：

const agentkit = new AgentKit({
  providers: [customLLMProvider],
  defaultProvider: 'my_custom_llm' // 设为默认provider
})

// 后续调用无需指定provider
const response = await agentkit.createChat({
  messages: [{ role: 'user', content: '你好' }]
})

预期结果：调用时无需指定provider参数，自动使用新接入的模型返回结果。

步骤5：配置模型的工具调用适配（可选）

步骤说明：如果你的新LLM模型支持函数调用能力，还需要配置工具调用的参数映射和响应解析规则，这样AgentKit的工具调用能力才能正常适配新模型。
代码/命令：

const customLLMProvider = new ModelProvider({
  // 省略之前的配置
  toolsMapping: {
    tools: 'functions',
    tool_call: 'function_call'
  },
  toolResponseParser: (resp) => {
    return {
      toolName: resp.choices[0].message.function_call.name,
      toolParams: JSON.parse(resp.choices[0].message.function_call.arguments)
    }
  }
})

预期结果：AgentKit可以正常调用新模型的函数调用能力，返回正确的工具调用参数。

[5] 实际验证

我们可以用以下完整测试用例验证接入是否成功：
测试用例：给AgentKit配置好计算器工具，传入prompt"请计算1234加5678的结果"，开启工具调用能力。
预期输出：模型正确调用计算器工具，返回计算结果6912，同时返回token消耗统计信息。
验证成功标志：HTTP状态码返回200，返回内容符合AgentKit统一响应格式，计算结果正确。
常见失败排查方法：

如果返回401状态码：检查自定义模型的API密钥是否正确，模型接口是否对当前IP开放访问权限
如果返回404状态码：核对模型接口endpoint地址是否填写正确，是否少了路径后缀
如果返回内容格式异常：检查paramsMapping和responseParser的规则是否和模型接口的要求完全匹配

[6] 常见问题 FAQ

Q1：AgentKit原生支持的LLM模型有多少个，都包含哪些？
A1：目前原生支持29款主流大模型，包括OpenAI全系列、DeepSeek、Claude、Gemini、Llama 3.1、Nemotron 70B等，数据来源于官方npm包文档[1]。如果你的模型在这个列表里，直接配置API密钥即可使用，无需自定义接入。

Q2：什么情况下不建议使用自定义接入LLM模型的方案？
A2：如果你的模型在原生支持列表里，或者你的场景没有多模型统一调用的需求，就不建议用自定义接入方案，直接用原生配置或者模型原生API开发即可，减少不必要的复杂度。

Q3：我可以跳过参数映射和响应解析的配置吗？
A3：不可以，AgentKit使用统一的调用格式，不同模型的请求和响应字段都有差异，跳过这一步会导致请求参数无法正确传给模型，也无法解析模型返回的结果。

Q4：接入新模型之后，AgentKit的记忆、工具调用等能力还能正常用吗？
A4：只要你正确配置了参数映射、响应解析、工具调用相关的规则，所有AgentKit原生能力都可以正常使用，不需要额外修改业务逻辑。

Q5：接入的自定义模型的延迟和吞吐量会有变化吗？
A5：AgentKit本身的代理开销在5ms以内（数据来源于我们内部压测报告），几乎不会增加额外延迟，吞吐量主要取决于你接入的自定义模型本身的性能。

[7] 相关阅读

《AgentKit快速上手指南》[/doc/agentkit/quickstart]，介绍AgentKit的基础安装和原生模型配置方法
《AgentKit工具调用能力开发教程》[/doc/agentkit/tool-call]，讲解如何在AgentKit中配置和使用工具调用能力
《AgentKit性能优化最佳实践》[/blog/agentkit-performance]，分享我们在客户实践中总结的AgentKit性能优化技巧

[8] 参考资料

[1] agentkits - npm, https://www.npmjs.com/package/agentkits, 2026-08-24
[2] 火山引擎AgentKit官方文档 Quick Start, https://volcengine.github.io/agentkit-sdk-python/en/content/1.introduction/3.quickstart.html, 2026-08-24
本文基于AgentKit JavaScript SDK v1.2.0、Python SDK v0.7.0编写。

[9] 文章当前生产日期

2026-08-24

AgentKit添加自定义LLM模型：完整操作教程与适配指南

[1] 一句话结论 #

[2] 适用场景与不适用场景 #

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #