从零构建12-Factor Agents项目：打造符合12要素原则的TypeScript智能体-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00582/article/details/148549729

从零构建12-Factor Agents项目：打造符合12要素原则的TypeScript智能体

12-factor-agents 模块化构建LLM应用，确保生产级可靠性与高效交付。项目地址: https://gitcode.com/gh_mirrors/12/12-factor-agents

本文将带你深入了解如何从零开始构建一个遵循12要素原则的TypeScript智能体(Agent)项目。12-Factor Agents项目提供了一套构建现代化、可扩展智能体应用的最佳实践指南。

项目初始化与环境搭建

准备工作

首先确保你的开发环境已经准备就绪：

安装Node.js 20或更高版本
准备npm包管理器
清理工作目录，确保从干净的状态开始

rm -rf baml_src/ && rm -rf src/

基础项目结构

我们从一个简单的TypeScript项目开始：

创建package.json文件，包含基本依赖：
- TypeScript 5.0+
- tsx (TypeScript执行环境)
- ESLint (代码质量检查工具)
配置TypeScript编译器选项(tsconfig.json)：
- 使用ES2017标准
- 启用严格类型检查
- 配置模块解析方式
添加.gitignore文件，排除不需要版本控制的目录

Hello World验证

创建一个简单的index.ts文件，包含基本的异步函数：

async function hello(): Promise<void> {
    console.log('hello, world!')
}

async function main() {
    await hello()
}

main().catch(console.error)

运行验证：

npx tsx src/index.ts

构建智能体核心功能

添加BAML集成

BAML(Boundary ML)是一个用于提示工程和结构化输出的工具：

安装BAML依赖：

npm install @boundaryml/baml

初始化BAML配置：

npx baml-cli init

创建智能体提示定义文件(agent.baml)：
- 定义DoneForNow响应类型
- 配置LLM客户端(Qwen3模型)
- 创建DetermineNextStep函数

实现CLI接口

构建命令行交互界面：

创建cli.ts处理命令行参数
实现Thread类管理对话上下文
开发agentLoop函数处理智能体主循环

运行智能体

设置环境变量后运行：

export BASETEN_API_KEY=your_key
export BASETEN_BASE_URL=your_url
npx tsx src/index.ts "你的消息"

扩展智能体能力：计算工具

添加计算工具定义

在BAML中定义四种基本计算工具：

type CalculatorTools = AddTool | SubtractTool | MultiplyTool | DivideTool

class AddTool {
    intent "add"
    a int | float
    b int | float
}
// 其他工具类似定义...

更新智能体响应类型

修改DetermineNextStep函数，使其能返回计算工具或DoneForNow响应：

function DetermineNextStep(
    thread: string 
-) -> DoneForNow {
+) -> CalculatorTools | DoneForNow {

实现工具处理逻辑

在agentLoop中添加工具调用处理：

case "add":
    thread.events.push({"type": "tool_call", "data": nextStep});
    const result = nextStep.a + nextStep.b;
    thread.events.push({"type": "tool_response", "data": result});
    continue;

测试与验证

添加BAML测试用例

为智能体功能添加测试验证：

test MathOperation {
  functions [DetermineNextStep]
  args {
    thread #"
      {
        "type": "user_input",
        "data": "can you multiply 3 and 4?"
      }
    "#
  }
  @@assert(intent, {{this.intent == "multiply"}})
}

运行测试

执行BAML测试套件：

npx baml-cli test

进阶功能：复杂计算处理

实现多步骤计算

智能体现在可以处理复杂的多步计算请求，例如： "can you multiply 3 and 4, then divide the result by 2 and then add 12 to that result"

添加中间状态测试

验证智能体在复杂计算中间状态的行为：

test LongMath {
  functions [DetermineNextStep]
  args {
    thread #"
      [
        {"type": "user_input", "data": "复杂计算请求"},
        {"type": "tool_call", "data": {"intent": "multiply", "a": 3, "b": 4}},
        {"type": "tool_response", "data": 12}
      ]
    "#
  }
}