迅捷OpenAI代理服务器
项目介绍
SwiftOpenAIAgentic
一个用于构建具有工具调用支持的AI代理的Swift SDK。SwiftOpenAIAgentic提供了一个干净且生产就绪的API，用于创建与MCP（模型上下文协议）集成并支持自定义工具的LLM应用程序。
功能
- ✅ OpenAI 工具调用 - 完全支持GPT-4、GPT-5及其他模型的功能调用
- ✅ MCP 集成 - 原生支持模型上下文协议服务器（HTTP传输）
- ✅ 本地工具 - 执行shell命令和脚本作为工具
- ✅ 自定义工具 - 易于实现的协议用于自定义工具开发
- ✅ 流式支持 - 流式最终响应以获得更好的用户体验
- ✅ 多轮对话 - 在多轮次中维护对话历史
- ✅ 事件委托 - 跟踪工具执行和代理事件
- ✅ 线程安全 - 使用Swift并发（异步/等待，演员）
- ✅ 生产就绪 - 错误处理、取消支持及资源清理
要求
- Swift 6.1+
- macOS 15+ / iOS 18+
- OpenAI API密钥
安装
Swift 包管理器
在你的Package.swift中添加SwiftOpenAIAgentic：
dependencies: [
.package(url: "https://github.com/mfreiwald/SwiftOpenAIAgentic.git", from: "1.0.0")
]
快速开始
基础聊天（无工具）
import SwiftOpenAIAgentic
let agenticAI = AgenticAI(apiKey: "your-openai-api-key")
let conversation = try await agenticAI.chat(
message: "2 + 2等于多少？",
model: "gpt-4o-mini"
)
print(conversation.last?.content ?? "")
具有MCP工具的代理
import SwiftOpenAIAgentic
// 配置MCP服务器
let mcpServer = MCPServerConfig(
name: "filesystem",
transport: "http",
url: "https://your-mcp-server.com/mcp"
)
let config = AgenticConfiguration(
mcpServers: [mcpServer]
)
let agenticAI = AgenticAI(apiKey: "your-api-key", configuration: config)
// 初始化（连接到MCP服务器）
await agenticAI.initialize()
// 启用工具进行聊天
let conversation = try await agenticAI.chat(
message: "列出当前目录中的文件",
model: "gpt-4o",
enabledTools: ["mcp__*"] // 启用所有MCP工具
)
print(conversation.last?.content ?? "")
await agenticAI.cleanup()
使用委托处理事件
class MyDelegate: AgentServiceDelegate {
func agentService(_ service: AgentService, willExecuteTool toolName: String, arguments: String, toolCallId: String) {
print("🔧 正在执行：\(toolName)")
}
func agentService(_ service: AgentService, didExecuteTool toolName: String, result: String, toolCallId: String) {
print("✅ 完成：\(toolName)")
}
func agentService(_ service: AgentService, didReceiveFinalResponse response: String) {
print("💬 响应：\(response)")
}
func agentService(_ service: AgentService, didReceiveStreamContent content: String) {
print(content, terminator: "")
}
func agentService(_ service: AgentService, didEncounterError error: Error) {
print("❌ 错误：\(error)")
}
}
let agenticAI = AgenticAI(apiKey: "your-api-key")
let delegate = MyDelegate()
agenticAI.setAgentDelegate(delegate)
_ = try await agenticAI.chat(
message: "在这里输入您的消息",
model: "gpt-4o",
enableStreaming: true
)
多轮对话
var conversation: [ChatCompletionParameters.Message] = []
// 第一轮
conversation = try await agenticAI.chat(
message: "法国的首都是哪里？",
model: "gpt-4o-mini"
)
// 第二轮 - 传递对话历史
conversation = try await agenticAI.chat(
message: "它的人口是多少？",
model: "gpt-4o-mini",
conversationHistory: conversation
)
自定义工具
import SwiftOpenAIAgentic
import SwiftOpenAI
class CalculatorTool: Tool {
let name = "local__calculator"
let description = "执行基本算术运算"
var parameters: JSONSchema {
JSONSchema(
type: .object,
properties: [
"operation": JSONSchema(type: .string),
"a": JSONSchema(type: .number),
"b": JSONSchema(type: .number)
],
required: ["operation", "a", "b"]
)
}
func execute(arguments: String) async throws -> String {
// 解析参数并执行计算
// 返回结果字符串
return "结果：42"
}
}
let agenticAI = AgenticAI(apiKey: "your-api-key")
agenticAI.registerTool(CalculatorTool())
let conversation = try await agenticAI.chat(
message: "计算123 * 456",
model: "gpt-4o-mini",
enabledTools: ["local__calculator"]
)
架构
SwiftOpenAIAgentic基于几个关键组件构建：
核心组件
- AgenticAI - 主入口点，高级API
- AgentService - 协调工具调用循环
- ToolExecutor - 工具的中央注册表和执行引擎
- Tool协议 - 所有工具（MCP、本地、自定义）的接口
MCP集成
- MCPClient - 基于演员的MCP服务器连接管理器
- MCPToolAdapter - 将MCP工具桥接到SwiftOpenAIAgentic工具协议
- MCPServerConfig - MCP服务器配置
本地工具
- LocalTool - 执行shell命令和脚本
- LocalToolsConfig - JSON格式的工具配置
配置
AgenticConfiguration
let config = AgenticConfiguration(
baseURL: "https://api.openai.com/v1", // 可选：自定义基础URL
debugEnabled: false, // 开启调试日志
mcpServers: [mcpServer1, mcpServer2], // 连接的MCP服务器
localToolsConfigPath: "tools.json" // 本地工具配置路径
)
let agenticAI = AgenticAI(apiKey: "key", configuration: config)
工具过滤
通过名称或通配符模式启用特定工具：
// 启用所有MCP工具
enabledTools: ["mcp__*"]
// 启用特定工具
enabledTools: ["mcp__filesystem__read_file"]
// 启用来自特定服务器的所有工具
enabledTools: ["mcp__github__*"]
// 混合MCP和本地工具
enabledTools: ["mcp__*", "local__grep"]
高级用法
取消
let agenticAI = AgenticAI(apiKey: "key")
// 开始长时间运行的操作
Task {
_ = try await agenticAI.chat(message: "长时间任务", model: "gpt-4o")
}
// 从另一个上下文中取消
agenticAI.cancel()
运行时MCP服务器管理
// 运行时连接到服务器
try await agenticAI.connectMCPServer(newServerConfig)
// 断开服务器连接
await agenticAI.disconnectMCPServer("servername")
// 获取可用工具
let tools = agenticAI.getAvailableTools()
print("MCP工具：\(tools.mcpTools.count)")
print("本地工具：\(tools.localTools.count)")
状态回调
agenticAI.setToolExecutorStatusCallback { message in
print("📡 \(message)")
}
agenticAI.setToolExecutorEventCallback { event in
switch event {
case .executionStarted(let tool, let args):
print("开始：\(tool)")
case .executionCompleted(let tool, let result):
print("完成：\(tool)")
case .executionFailed(let tool, let error):
print("失败：\(tool) - \(error)")
}
}
示例
查看Examples目录中的完整可运行示例：
- BasicExample - 展示所有核心功能
- 更多示例即将推出！
MCP服务器支持
SwiftOpenAIAgentic目前支持：
- ✅ HTTP传输（包括Zapier MCP服务器）
- ⏳ Stdio传输（即将推出 - 需要进程包装器）
设置MCP服务器
对于基于HTTP的MCP服务器（例如Zapier）：
let server = MCPServerConfig(
name: "zapier",
transport: "http",
url: "https://actions.zapier.com/mcp/v1/servers/YOUR_ID"
)
贡献
欢迎贡献！请随时提交Pull Request。
许可证
[您的许可证这里]
致谢
SwiftOpenAIAgentic受到SwiftOpenAICLI的启发，并从中提取了核心功能，适应为通用SDK。
依赖项
- SwiftOpenAI - OpenAI API客户端
- swift-sdk - MCP Swift SDK