Agentica，AI 函数调用框架

专注于 AI 函数调用的智能体 AI 框架。

别再害怕开发 AI 智能体了。只需列出以下三种协议中的函数即可。这就是你进行 AI 智能体开发需要做的全部工作。

• TypeScript 类
• Swagger/OpenAPI 文档
• MCP（模型上下文协议）服务器

想打造一个电商智能体吗？引入电商相关功能即可。需要一个新闻智能体吗？从报社获取 API 功能就行了。只要准备好你需要的任何功能，它就能成为一个 AI 智能体。

你是 TypeScript 开发者吗？那你就已经是 AI 开发者了。熟悉后端开发吗？那你已经对 AI 开发非常熟练了。任何能够编写函数的人，都能创建 AI 智能体。

import { Agentica, assertHttpController } from "@agentica/core";
import OpenAI from "openai";
import typia from "typia";

import { MobileFileSystem } from "./services/MobileFileSystem";

const agent = new Agentica({
  vendor: {
    api: new OpenAI({ apiKey: "********" }),
    model: "gpt-4o-mini",
  },
  controllers: [
    // 来自 TypeScript 类的函数
    typia.llm.controller<MobileFileSystem>(
      "filesystem",
      new MobileFileSystem(),
    ),
    // 来自 Swagger/OpenAPI 的函数
    assertHttpController({
      name: "shopping",
      model: "chatgpt",
      document: await fetch(
        "https://shopping-be.wrtn.ai/editor/swagger.json",
      ).then(r => r.json()),
      connection: {
        host: "https://shopping-be.wrtn.ai",
        headers: { Authorization: "Bearer ********" },
      },
    }),
  ],
});
await agent.conversate("我想买 MacBook Pro");

📦 设置

$ npx agentica start <目录>

----------------------------------------
 Agentica 设置向导
----------------------------------------
? 包管理器（使用方向键）
  > npm
    pnpm
    yarn（berry 不支持）
? 项目类型
    NodeJS 智能体服务器
  > NestJS 智能体服务器
    React 客户端应用
    独立应用
? 内置控制器（可多选）
    （无）
    Google 日历
    Google 新闻
  > Github
    Reddit
    Slack
    ...

设置向导可以帮助你根据需求创建一个新项目。

作为参考，在选择项目类型时，除了“独立应用”之外的任何选项都会实现 WebSocket 协议 用于客户端与服务器之间的通信。

有关完整的设置说明，请访问我们的 入门指南。

💻 体验区

在安装之前，可以通过我们的 交互式体验区 亲身体验 Agentica。

我们的演示展示了 Agentica 在不同集成方式下函数调用功能的强大与简单性。

• TypeScript 类
• Swagger/OpenAPI 文档
• 企业级电商智能体

📚 文档资源

您可以在我们的 官方网站 找到全面的资源。

• 首页
• 指南文档
  • 设置
  • 概念
  • 核心库
  • WebSocket 协议
  • 插件模块
• 教程
  • 生产力
  • 编码
  • React Native
  • 企业
• API 文档
• YouTube
• 论文

https://github.com/user-attachments/assets/2f2a4cdc-6cf1-4304-b82d-04a8ed0be0dd

教程视频：https://www.youtube.com/@wrtnlabs

🌟 为什么选择 Agentica？

flowchart
  subgraph "JSON Schema 规范"
    schemav4("JSON Schema v4 ~ v7") --升级--> emended[["OpenAPI v3.1（修订版）"]]
    schema2910("JSON Schema 2019-03") --升级--> emended
    schema2020("JSON Schema 2020-12") --修订--> emended
  end
  subgraph "Agentica"
    emended --"人工智能"--> fc{{"AI 函数调用"}}
    fc --"OpenAI"--> chatgpt("ChatGPT")
    fc --"Google"--> gemini("Gemini")
    fc --"Anthropic"--> claude("Claude")
    fc --"High-Flyer"--> deepseek("DeepSeek")
    fc --"Meta"--> llama("Llama")
    chatgpt --"3.1"--> custom(["自定义 JSON Schema"])
    gemini --"3.0"--> custom(["自定义 JSON Schema"])
    claude --"3.1"--> standard(["标准 JSON Schema"])
    deepseek --"3.1"--> standard
    llama --"3.1"--> standard
  end

Agentica 通过以下策略增强了 AI 函数调用的能力：

• 编译器驱动开发：无需手动编写，直接利用编译器技术自动构建函数调用模式。
• JSON Schema 转换：自动处理不同大模型供应商之间的规范差异，确保无论你选择哪种 AI 模型都能无缝集成。
• 验证反馈：检测并纠正 AI 在参数构造中的错误，大幅减少失误、提升可靠性。
• 选择器智能体：筛选候选函数，以最小化上下文使用量、优化性能并降低 token 消耗。

得益于这些创新，Agentica 使 AI 函数调用比以往更加简单、安全和精准。开发者只需准备与特定用例相关的函数，开发过程便更为直观；而扩展智能体的能力也只需增删函数即可，十分简便。

2023 年，当 OpenAI 宣布推出函数调用功能时，许多人预测基于函数调用的 AI 开发将成为主流。然而，实际上由于函数调用的复杂性和不稳定性，AI 开发的趋势却转向了工作流式智能体。这种工作流式智能体虽然灵活度较低，且需针对特定场景定制，却迅速占据了 AI 智能体生态系统的主导地位。

值得一提的是，随着 Agentica 解决了函数调用的复杂性与不稳定性问题，重新拥抱函数驱动型 AI 开发的时机已经到来。

💬 社区与支持

如需支持、提问或提供反馈，请加入我们的 Discord 社区：

⚖️ 许可证

Agentica 是开源项目，采用 MIT 许可证 授权。

Agentica 快速上手指南

Agentica 是一个专注于 AI 函数调用 (Function Calling) 的智能体框架。它允许开发者直接将 TypeScript 类、Swagger/OpenAPI 文档或 MCP 服务器转换为 AI 智能体，无需手动编写复杂的提示词或工作流。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Windows, macOS, 或 Linux
• Node.js: 建议安装 LTS 版本 (v18 或更高)
• 包管理器: npm, pnpm, 或 yarn
• API Key: 需要准备一个大模型服务商的 API Key (如 OpenAI, Google Gemini, Anthropic Claude 等)

国内开发者提示：如果访问 npm 官方源较慢，建议使用国内镜像源加速安装。

# 临时使用淘宝镜像源
npm config set registry https://registry.npmmirror.com

2. 安装步骤

Agentica 提供了交互式向导来快速初始化项目。

步骤一：运行初始化命令

在终端中执行以下命令（将 <your-project-name> 替换为你的项目目录名）：

npx agentica start <your-project-name>

步骤二：配置项目选项

运行命令后，向导会引导你完成以下配置（使用方向键选择，回车确认）：

1. Package Manager: 选择包管理器 (推荐 npm 或 pnpm)。
2. Project Type: 选择项目类型。
   • NodeJS Agent Server: 纯后端服务。
   • NestJS Agent Server: 基于 NestJS 的后端服务 (推荐)。
   • React Client Application: 带前端界面的应用。
   • Standalone Application: 独立应用程序。
3. Embedded Controllers: 选择预置的功能模块 (可多选)，例如：
   • Github: GitHub 操作功能
   • Google Calendar: 日历管理
   • Slack: 消息通知
   • (none): 不选择任何预置模块，完全自定义。

步骤三：安装依赖

向导完成后，进入项目目录并安装依赖：

cd <your-project-name>
npm install
# 或者如果你选择了 pnpm/yarn
# pnpm install
# yarn install

3. 基本使用

Agentica 的核心逻辑非常简单：定义函数 -> 注册控制器 -> 对话。

以下是一个最简化的代码示例，展示如何结合 TypeScript 类 和 OpenAPI 文档 创建一个购物助手智能体。

代码示例 (index.ts)

import { Agentica, assertHttpController } from "@agentica/core";
import OpenAI from "openai";
import typia from "typia";

// 1. 定义你的业务逻辑类 (TypeScript Class)
class MobileFileSystem {
  async writeFile(path: string, content: string): Promise<void> {
    console.log(`Writing to ${path}: ${content}`);
  }
  
  async readFile(path: string): Promise<string> {
    return `Content of ${path}`;
  }
}

const agent = new Agentica({
  // 2. 配置大模型供应商
  vendor: {
    api: new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
    model: "gpt-4o-mini",
  },
  controllers: [
    // 方式 A: 直接注册 TypeScript 类
    // typia 会自动分析类型生成 Schema
    typia.llm.controller<MobileFileSystem>(
      "filesystem",
      new MobileFileSystem(),
    ),
    
    // 方式 B: 注册 Swagger/OpenAPI 文档 (例如电商接口)
    assertHttpController({
      name: "shopping",
      model: "chatgpt",
      // 加载远程或本地的 Swagger JSON
      document: await fetch(
        "https://shopping-be.wrtn.ai/editor/swagger.json",
      ).then(r => r.json()),
      connection: {
        host: "https://shopping-be.wrtn.ai",
        headers: { Authorization: "Bearer YOUR_SHOPPING_API_KEY" },
      },
    }),
  ],
});

// 3. 开始对话
async function main() {
  const response = await agent.conversate("我想买一台 MacBook Pro，并请帮我记录到文件中。");
  console.log(response);
}

main().catch(console.error);

核心特性说明

• 自动 Schema 生成: 无需手写 JSON Schema，Agentica 利用编译器技术从 TypeScript 类型或 OpenAPI 文档自动生成。
• 多模型兼容: 自动处理不同大模型厂商（OpenAI, Google, Anthropic 等）之间的 Schema 格式差异。
• 错误自愈: 内置验证反馈机制，如果 AI 生成的参数有误，框架会自动检测并引导 AI 修正，提高稳定性。

下一步

• 在线体验: 访问 Agentica Playground 直接在浏览器中测试不同场景。
• 详细文档: 查阅 官方文档 了解 WebSocket 协议、插件开发和高级配置。