关键词

AI Agent编排Kubernetes Operator工具集成异步执行云原生应用

使用说明

项目简介

KubeChain 是一个构建在 Kubernetes 上的云原生 AI Agent 编排器。它专注于简化 AI Agent 的构建和管理，特别是在需要异步执行 LLM 推理和长时间工具调用的场景下。KubeChain 通过 Kubernetes CRD (Custom Resource Definitions) 扩展了 Kubernetes API，允许用户以声明式的方式定义和管理 LLM、Agent、Tool 和 Task 等 AI 应用组件。

核心概念:

  • LLM (Large Language Model): 定义了使用的 LLM 提供商 (如 OpenAI) 和 API 密钥。
  • Agent: 由 LLM、系统 Prompt 和 Tool 组成，是执行任务的主体。
  • Tool: Agent 可以调用的外部功能，可以是函数、API、Docker 容器或其他 Agent。KubeChain 支持通过 MCP Server 集成 Tool，允许 Agent 调用符合 Model Context Protocol 标准的外部服务。
  • Task: Agent 需要执行的具体任务，包含用户消息和 Agent 引用。
  • TaskRun: Task 的一次执行实例，记录了任务运行时的上下文信息。

主要功能点

  • MCP Server 集成: 支持将外部服务注册为 MCP Server Tool，供 Agent 调用，扩展 Agent 的能力。
  • Kubernetes 原生架构: 基于 Kubernetes Operator 构建，利用 CRD 管理 AI 组件，易于部署和扩展。
  • 异步和持久化 Agent 执行: 支持 Agent 异步执行 LLM 推理和 Tool 调用，保证任务的持久性和可靠性。
  • 动态工作流规划: Agent 可以在执行过程中重新规划和调整工作流程。
  • 可观测的控制循环架构: 易于调试和监控 Agent 的执行过程。

安装步骤

  1. 前提条件:

    • 'kubectl' - Kubernetes 命令行工具
    • 'kind' - 用于本地 Kubernetes 集群 (可选)
    • OpenAI API Key - 用于 LLM 功能 (如果使用 OpenAI LLM)
    • Docker - 用于构建和运行容器镜像 (如果需要本地构建)

  2. 设置本地 Kubernetes 集群 (可选):

    kind create cluster --config kubechain-example/kind/kind-config.yaml

  3. 部署 KubeChain Operator:

    kubectl apply -f https://raw.githubusercontent.com/humanlayer/smallchain/refs/heads/main/kubechain/config/release/latest.yaml

服务器配置

KubeChain 本身作为 Kubernetes Operator 运行，不直接作为 MCP 服务器供客户端连接。

KubeChain 中 MCP Server 的配置 是指在 KubeChain 中定义 'MCPServer' 资源，用于集成 外部 MCP 服务器 作为 Tool，供 Agent 调用。

在 KubeChain 中配置 MCP Server Tool，需要创建 'MCPServer' 类型的 Kubernetes 资源。以下是一个 'MCPServer' 资源的配置示例 (YAML 格式)：

apiVersion: kubechain.humanlayer.dev/v1alpha1
kind: MCPServer
metadata:
  name: fetch-server # MCP Server 的名称，Agent 通过此名称引用
spec:
  type: "stdio" # MCP Server 的传输协议，例如 stdio, sse, websocket
  command: "uvx" # 启动 MCP Server 的命令
  args: ["mcp-server-fetch"] # 启动命令的参数

配置参数说明 (JSON 格式，供 MCP 客户端参考，但 KubeChain 中直接使用 YAML 配置 CR)：

{
  "server name": "fetch-server", // MCPServer 资源的 metadata.name
  "command": "uvx", // spec.command，MCP 服务器的可执行文件路径或命令
  "args": ["mcp-server-fetch"] // spec.args，传递给 MCP 服务器的命令行参数
  // 其他可选配置，例如传输协议类型 (type) 等，根据 MCPServer 资源的 spec 定义进行配置
}

注意: MCP 客户端 (例如基于 MCP 协议构建的 LLM 应用) 不是直接连接到 KubeChain，而是连接到用户自己部署的、符合 MCP 协议的外部服务。KubeChain 的 'MCPServer' 资源用于声明如何启动和连接这些外部 MCP 服务器，并将其作为 Tool 集成到 KubeChain 的 Agent 中。

基本使用方法

  1. 创建 LLM 资源: 定义要使用的 LLM 模型。

    kubectl apply -f - <<EOF
apiVersion: kubechain.humanlayer.dev/v1alpha1
kind: LLM
metadata:
  name: gpt-4o
spec:
  provider: openai
  apiKeyFrom:
    secretKeyRef:
      name: openai
      key: OPENAI_API_KEY
EOF

  2. 创建 Agent 资源: 定义 AI Agent，关联 LLM 和系统 Prompt。

    kubectl apply -f - <<EOF
apiVersion: kubechain.humanlayer.dev/v1alpha1
kind: Agent
metadata:
  name: my-assistant
spec:
  llmRef:
    name: gpt-4o
  system: |
    You are a helpful assistant. Your job is to help the user with their tasks.
EOF

  3. 创建 MCPServer 资源 (如果需要集成 MCP Server Tool): 定义要集成的 MCP Server 工具。

    kubectl apply -f - <<EOF
apiVersion: kubechain.humanlayer.dev/v1alpha1
kind: MCPServer
metadata:
  name: fetch
spec:
  type: "stdio"
  command: "uvx"
  args: ["mcp-server-fetch"]
EOF

  4. 更新 Agent 资源，添加 Tool 引用 (如果使用了 MCP Server Tool): 将 MCP Server Tool 添加到 Agent 的 Tool 列表中。

    kubectl apply -f - <<EOF
apiVersion: kubechain.humanlayer.dev/v1alpha1
kind: Agent
metadata:
  name: my-assistant
spec:
  llmRef:
    name: gpt-4o
  system: |
    You are a helpful assistant. Your job is to help the user with their tasks.
  tools: # 注意这里是 tools，而不是 mcpServers
    - name: fetch # 引用 Tool 的名称，这里应该是 Tool 资源的名称，而不是 MCPServer 的名称
EOF

    重要更正: 'AgentSpec' 中使用 'tools' 字段引用 Tool，而不是 'mcpServers'。'mcpServers' 字段在示例中出现是错误的，应该使用 'Tool' 资源来封装 MCP Server 工具，并在 'Agent' 中引用 'Tool'。

    正确做法: 应该先创建 'Tool' 资源，'Tool' 资源的 'spec' 中 'execute' 部分配置 'externalAPI' 或者其他方式来调用 MCP Server。然后在 'Agent' 的 'spec.tools' 中引用 'Tool' 资源。示例中的 'MCPServer' 资源实际上是用来管理和部署 MCP Server 的，但 KubeChain 的核心设计似乎更倾向于将 MCP Server 视为一种 'Tool' 的实现方式，而不是直接作为 Agent 的配置项。

    更正后的 Tool 资源示例 (用于封装 MCP Server Tool):

    apiVersion: kubechain.humanlayer.dev/v1alpha1
kind: Tool
metadata:
  name: fetch-tool # Tool 的名称，Agent 通过此名称引用
spec:
  toolType: "externalAPI" # 或者其他合适的 ToolType，取决于实际 Tool 的实现方式
  name: "fetch_url" # Tool 的功能名称，用于 LLM 调用
  description: "Fetches content from a URL" # Tool 的描述
  parameters: # Tool 的参数 schema
    raw: |
      {
        "type": "object",
        "properties": {
          "url": { "type": "string" }
        },
        "required": ["url"]
      }
  execute:
    externalAPI: # 假设使用 externalAPI 类型 Tool 来调用 MCP Server
      url: "http://your-mcp-server-address/api/jsonrpc" # 替换为你的 MCP Server 地址
      method: "POST" # MCP 通常使用 POST 请求
      # ... 其他 externalAPI 配置，例如认证信息等

    然后，在 'Agent' 中引用 'fetch-tool'：

    apiVersion: kubechain.humanlayer.dev/v1alpha1
kind: Agent
metadata:
  name: my-assistant
spec:
  llmRef:
    name: gpt-4o
  system: |
    You are a helpful assistant. Your job is to help the user with their tasks.
  tools:
    - name: fetch-tool # 引用 Tool 资源的名称

  5. 创建 Task 资源: 提交任务给 Agent 执行。

    kubectl apply -f - <<EOF
apiVersion: kubechain.humanlayer.dev/v1alpha1
kind: Task
metadata:
  name: fetch-task
spec:
  agentRef:
    name: my-assistant
  message: "What is on the front page of news.google.com?"
EOF

  6. 查看 TaskRun 状态: 查看任务执行结果。

    kubectl get taskrun
kubectl describe taskrun <taskrun-name>

总结: KubeChain 通过 Kubernetes CRD 提供了 Agent、Tool 和 Task 的管理能力，并支持通过 Tool 集成外部 MCP Server，扩展 Agent 的功能。用户需要在 KubeChain 中定义 'Tool' 资源来封装 MCP Server 工具，并在 'Agent' 中引用这些 'Tool'，从而实现 Agent 对 MCP Server 功能的调用。

信息

分类

开发者工具

访问项目