使用说明

项目简介

KubeChain 是一个构建在 Kubernetes 上的云原生 AI Agent 编排器。它专注于支持持久化的外循环 Agent，能够处理 LLM 推理和长时间运行的工具调用的异步执行。KubeChain 旨在简化 AI Agent 的构建和管理，为需要异步工具调用（如人工交互或委托任务给其他 Agent）的 Agent 提供强大的持久性和可靠性保障。

主要功能点

• Kubernetes 原生架构：基于 Kubernetes Operator 构建，利用 CRD（自定义资源定义）管理 LLM、Agent、工具、任务和任务运行。
• 持久化 Agent 执行：通过在基础设施层实现类似 async/await 的机制，在工具调用或 Agent 委托发生时，对会话链进行检查点保存，并在操作完成时从检查点恢复。
• 动态工作流规划：允许 Agent 在执行过程中重新规划和调整工作流程。
• 可观测的控制循环架构：采用简单、可观测的控制循环架构，便于调试和监控 Agent 执行过程。
• 可扩展性：利用 Kubernetes 的可扩展性和弹性，支持可靠的分布式异步 Agent 运行。
• 人工审批和输入：支持通过工具接口实现 Agent 请求人工输入或等待审批的持久化任务执行。

安装步骤

1. 前提条件：

   • kubectl
   • kind (用于本地 Kubernetes 集群)
   • OpenAI API Key
   • Docker

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

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

3. 添加 OpenAI API Key 作为 Kubernetes Secret：

   kubectl create secret generic openai \
     --from-literal=OPENAI_API_KEY=$OPENAI_API_KEY \
     --namespace=default
   

4. 部署 KubeChain Operator：

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

5. 创建 LLM 资源：

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

6. 创建 Agent 资源：

   cat <<EOF | kubectl apply -f -
   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
   

7. 运行 Task：

   cat <<EOF | kubectl apply -f -
   apiVersion: kubechain.humanlayer.dev/v1alpha1
   kind: Task
   metadata:
     name: hello-world-task
   spec:
     agentRef:
       name: my-assistant
     message: "What is the capital of the moon?"
   EOF
   

服务器配置 (MCP Server 配置示例)

以下 JSON 配置描述了 MCP 客户端如何配置连接到 KubeChain 部署的 MCP 服务器工具（例如 'fetch' 工具）。您需要在 MCP 客户端中配置类似以下的连接信息，以便客户端能够与 KubeChain 集群中的 MCP 服务器建立通信并调用工具。

{
  "server name": "fetch",
  "transport": "stdio",
  "command": "uvx",
  "args": ["mcp-server-fetch"],
  "description": "此配置将 MCP 客户端连接到一个通过 stdio 传输运行的 'fetch' MCP 服务器。'command' 指定要运行的可执行文件 ('uvx')，'args' 提供命令的参数 ('mcp-server-fetch')。'server name' 用于在 Agent 配置中引用此服务器。"
}

请注意：实际配置可能需要根据您使用的 MCP 客户端的具体要求进行调整。以上 JSON 仅为示例，展示了连接到基于 stdio 传输的 MCP 服务器所需的基本信息。MCP 客户端需要能够解析此类配置并建立连接。

基本使用方法

1. 使用 'kubectl apply' 命令创建 'LLM'、'Agent'、'Task' 等 Kubernetes 资源来定义和运行 AI Agent。
2. 通过创建 'MCPServer' 资源将外部工具集成到 KubeChain 中，并将其关联到您的 'Agent'。
3. 使用 'kubectl get' 和 'kubectl describe' 命令监控资源状态和任务执行进度。
4. 通过查看 'TaskRun' 资源的 'status.output' 字段获取 Agent 的最终输出结果。