关键词

AI代理LLM工具上下文服务Kotlin AI多模态应用

项目简介

Predictable Agents是一个基于Kotlin语言构建的多平台AI应用开发库，旨在通过类型安全和函数式编程范式，帮助开发者构建可预测的AI应用。它提供了灵活的Agent和Tool机制，可以与OpenAI、OpenRouter等大模型服务集成。其中，MCP模块允许开发者将其创建的AI代理和工具，以标准化的Model Context Protocol (MCP) 格式对外提供服务，从而实现与任何MCP兼容的LLM客户端进行高效、安全的上下文交互。

主要功能点

  • 类型安全的AI交互： 自动从Kotlin数据类生成Schema，确保AI输入输出的类型安全。
  • 多平台支持： 可以在JVM、Android、iOS、Linux和WASM等多个平台运行。
  • 工具集成： 将自定义函数封装为AI工具，扩展AI代理的能力。
  • 代理组合： 允许将Agent作为工具使用，构建复杂的AI处理流程和多代理系统。
  • MCP服务器： 核心功能是启动一个符合Model Context Protocol (MCP) 标准的服务器，将Predictable Agents中定义的AI工具和代理暴露给外部MCP客户端。
  • JSON-RPC通信： MCP服务器通过JSON-RPC协议与客户端通信，支持SSE (Server-Sent Events) 等多种传输协议。
  • 会话管理与能力声明： 提供会话管理，并向客户端声明服务器所提供的工具能力。

安装步骤

Predictable Agents库及其MCP支持模块可以轻松集成到您的Kotlin项目中。

  1. 在您的 'build.gradle.kts' 文件中，添加以下依赖： 
    dependencies {
    // Predictable Agents 核心库
    implementation("com.predictablemachines:agents:0.1.0-SNAPSHOT")
    
    // 可选：MCP 服务器支持模块
    implementation("com.predictablemachines:mcp:0.1.0-SNAPSHOT")
}
  2. 如果您正在进行多平台开发，请在 'kotlin { sourceSets { ... } }' 块中为 'commonMain' 添加依赖： 
    kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("com.predictablemachines:agents:0.1.0-SNAPSHOT")
                // 如果需要在commonMain中使用MCP相关API，也在此处添加mcp模块
                // implementation("com.predictablemachines:mcp:0.1.0-SNAPSHOT") 
            }
        }
    }
}
  3. 确保您的环境已配置必要的API密钥，例如OpenAI或OpenRouter，通常作为环境变量设置： 
    export OPENAI_API_KEY="your-api-key"
export OPENROUTER_API_KEY="your-openrouter-key" # 可选
export OPENAI_API_URL="https://api.openai.com/v1/" # 可选：自定义API端点

服务器配置

Predictable Agents的MCP服务器通常通过Ktor框架启动，并暴露预定义的AI工具和代理。MCP客户端连接此服务器时，需要指定正确的配置信息才能与MCP服务器建立连接。

以下是一个典型的MCP客户端需要配置的信息示例，用于连接Predictable Agents MCP服务器：

{
  "servers": {
    "my-predictable-server": {
      "name": "我的Predictable AI服务",
      "namespace": "predictable",
      "description": "由Predictable Agents驱动的MCP服务",
      "config": {
        "type": "sse",
        "url": "http://localhost:8080/sse",
        "headers": {
          "Authorization": "Bearer YOUR_CUSTOM_TOKEN"
        }
      }
    }
  }
}
  • server name: 'my-predictable-server' (您为该服务器实例定义的唯一名称)
  • type: 'sse' (表示服务器通过Server-Sent Events协议通信，这是Predictable Agents MCP服务器默认的一种常用传输协议)
  • url: 'http://localhost:8080/sse' (MCP服务器的监听地址和SSE端点。请确保端口和主机与您实际启动服务器时设置的一致)
  • headers: (可选) 如果服务器需要认证或其他自定义请求头，可以在此配置。例如，'"Authorization": "Bearer YOUR_CUSTOM_TOKEN"'。
  • 如果您将MCP服务器打包为可执行JAR并通过 'java -jar your-server-application.jar' 方式启动，并希望MCP客户端能自动管理其生命周期，那么客户端配置的 'type' 也可以是 'stdio'，并提供启动命令和参数： 
    {
  "type": "stdio",
  "command": "java",
  "args": [
    "-jar",
    "your-server-application.jar",
    // 如果您的应用需要，可以添加启动参数，例如：
    // "--port", "8080", 
    // "--host", "0.0.0.0"
  ],
  "env": {
    "OPENAI_API_KEY": "YOUR_OPENAI_KEY" // 传入服务器所需的API密钥
  }
}
    • command: 'java' (启动Java应用程序的命令)
    • args: '"-jar", "your-server-application.jar"' (执行JAR文件的参数。'your-server-application.jar' 是您编译打包后的Predictable Agents MCP服务器应用的JAR文件名)
    • env: (可选) 额外的环境变量，如 'OPENAI_API_KEY'，用于在服务器进程中配置AI服务提供商的API密钥。

基本使用方法

启动Predictable Agents MCP服务器的步骤如下：

  1. 定义您的AI工具或代理： 例如，创建一个简单的翻译工具：

    import predictable.Tool
import predictable.tool.KotlinSchema
import kotlinx.serialization.Serializable
import kotlinx.coroutines.runBlocking

@Serializable
data class TranslationInput(val text: String, val targetLanguage: String)

@Serializable
data class TranslationOutput(val translatedText: String, val sourceLanguage: String)

val translator = Tool(
    name = "translator",
    description = "Translates text to different languages",
    schema = KotlinSchema(
        TranslationInput.serializer(),
        TranslationOutput.serializer()
    )
) { input ->
    // 您的翻译逻辑
    TranslationOutput(
        translatedText = "Translated: ${input.text} to ${input.targetLanguage}",
        sourceLanguage = "auto-detected"
    )
}

  2. 启动MCP服务器： 使用 'startKtorMCPServer' 函数启动服务器，并将您定义的工具列表传入。

    import predictable.mcp.server.MCPServer.startKtorMCPServer

fun main() = runBlocking {
    val server = startKtorMCPServer(
        tools = listOf(translator), // 传入您定义的工具
        port = 8080,
        host = "0.0.0.0",
        serverName = "my-translation-server", // 服务器名称
        serverVersion = "1.0.0" // 服务器版本
    )
    
    println("MCP Server running at http://localhost:8080/sse")
    server.start(wait = true) // 启动服务器并等待
}

    将上述代码编译打包成一个可执行的JAR文件，即可作为MCP服务器运行。

  3. MCP客户端连接： 当MCP服务器运行后，任何MCP兼容的客户端（例如，另一个Predictable Agents客户端、VS Code插件或支持MCP的LLM前端）都可以通过配置服务器的URL ('http://localhost:8080/sse') 来发现并调用您暴露的工具。

    例如，使用Predictable Agents作为MCP客户端连接：

    import predictable.mcp.client.MCPClient
import predictable.mcp.config.MCPConfig
import predictable.mcp.config.MCPServerConfig
import predictable.mcp.config.ServerConfig
import kotlinx.serialization.json.*

suspend fun connectToMCPServer() {
    val config = MCPConfig(
        servers = mapOf(
            "remote-server" to MCPServerConfig(
                name = "Remote Translation Server",
                namespace = "remote",
                description = "远程翻译服务",
                config = ServerConfig.SSE( // 使用SSE协议
                    url = "http://localhost:8080/sse"
                )
            )
        )
    )
    
    MCPClient(config) { client ->
        val tools = client.tools() // 发现服务器上的工具
        val translatorTool = tools.first { it.name == "translator" }
        
        val input = buildJsonObject {
            put("text", "Hello world")
            put("targetLanguage", "Spanish")
        }
        val result = translatorTool.invoke(input) // 调用翻译工具
        
        println("Translation result: $result")
    }
}

信息

分类

AI与计算

访问项目