Agent Control Plane (ACP) 使用说明

项目简介

Agent Control Plane (ACP) 是一个构建在 Kubernetes 上的云原生平台，用于编排和管理 AI Agent。它专注于为长期运行的 Agent 提供基础设施支持，特别是在异步工具调用和需要人工参与的工作流中。ACP 旨在简化 AI Agent 的部署和管理，并提供高可靠性和可扩展性。

主要功能点

Kubernetes 原生架构: 基于 Kubernetes CRD 构建，易于部署和管理。
持久化 Agent 执行: 支持 Agent 异步执行 LLM 推理和长时间运行的工具调用，保证任务的持久性和可靠性。
动态工作流: 允许 Agent 在执行过程中重新规划和调整工作流程。
可观测的控制回路: 架构清晰，易于理解和调试 Agent 的执行过程。
可扩展性: 利用 Kubernetes 的扩展能力，支持大规模 Agent 部署。
人工审批与介入: 支持在 Agent 工作流中集成人工审批环节，例如在调用某些工具前请求人工确认。
MCP 工具集成: 支持通过 MCP 服务器集成各种工具，扩展 Agent 的功能。

安装步骤

前提条件:
- Kubernetes 集群 (例如 Kind)
- kubectl 命令行工具
- Docker (用于本地构建镜像)
- OpenAI API Key (或其他 LLM 提供商 API Key)
本地集群部署:
```
kind create cluster
```

部署 ACP Operator:

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

创建 LLM 资源:

kubectl create secret generic openai --from-literal=OPENAI_API_KEY=$OPENAI_API_KEY
kubectl apply -f - <<EOF
apiVersion: acp.humanlayer.dev/v1alpha1
kind: LLM
metadata:
  name: gpt-4o
spec:
  provider: openai
  parameters:
    model: gpt-4o
  apiKeyFrom:
    secretKeyRef:
      name: openai
      key: OPENAI_API_KEY
EOF

创建 Agent 资源:

kubectl apply -f - <<EOF
apiVersion: acp.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

创建 Task 资源:

kubectl apply -f - <<EOF
apiVersion: acp.humanlayer.dev/v1alpha1
kind: Task
metadata:
  name: hello-world-1
spec:
  agentRef:
    name: my-assistant
  userMessage: "What is the capital of the moon?"
EOF

服务器配置 (MCPServer)

ACP 通过 'MCPServer' 资源集成 MCP 服务器作为 Agent 的工具。以下是一个 'MCPServer' 配置示例：

apiVersion: acp.humanlayer.dev/v1alpha1
kind: MCPServer
metadata:
  name: fetch
spec:
  transport: "stdio" # MCP 服务器传输协议，可选 "stdio" 或 "http"
  command: "uvx"     # 启动 MCP 服务器的命令 (当 transport 为 "stdio" 时必需)
  args: ["mcp-server-fetch"] # 传递给 MCP 服务器的参数 (当 transport 为 "stdio" 时可选)
  # approvalContactChannel: # (可选) 人工审批通道配置
  #   name: approval-channel

配置说明 (MCPServer):

'name': MCPServer 资源的名称，在 Agent 中引用。
'spec.transport': 指定 MCP 服务器的传输协议，支持 'stdio' (标准输入输出) 或 'http'。
'spec.command': 当 'transport' 为 'stdio' 时，指定启动 MCP 服务器的命令，例如 'uvx'。
'spec.args': 当 'transport' 为 'stdio' 时，可选的参数列表，例如 '["mcp-server-fetch"]'。
'spec.approvalContactChannel': (可选) 配置人工审批通道，用于在工具执行前请求人工批准。

MCP 客户端配置: MCP 客户端需要配置 'MCPServer' 资源的 'spec.command' 和 'spec.args' 以连接到 MCP 服务器。例如，对于 'fetch' 这个 'MCPServer' 资源，客户端需要配置启动命令和参数为 'command: "uvx"', 'args: ["mcp-server-fetch"]'。

基本使用方法

部署 ACP: 按照安装步骤部署 ACP Operator 到 Kubernetes 集群。
定义 LLM: 创建 'LLM' 资源，配置 LLM 提供商和 API 密钥。
创建 Agent: 创建 'Agent' 资源，关联 LLM 并设置系统 Prompt。
集成 MCP 工具: 创建 'MCPServer' 资源，配置 MCP 服务器连接信息。在 'Agent' 资源中引用 'MCPServer'，使 Agent 能够使用 MCP 工具。
执行 Task: 创建 'Task' 资源，指定 Agent 和用户消息，与 Agent 进行交互。
观察 Task 状态: 通过 'kubectl get task' 或 'kubectl describe task' 查看 Task 的执行状态和输出结果。

关键词