内容
# 🚀 ArgoCD AI 代理
[](https://www.python.org/)
[](https://python-poetry.org/)
[](LICENSE)
[](https://github.com/cnoe-io/openapi-mcp-codegen/actions/workflows/conventional_commits.yml)
[](https://github.com/cnoe-io/openapi-mcp-codegen/actions/workflows/ruff.yml)
[](https://github.com/cnoe-io/openapi-mcp-codegen/actions/workflows/superlinter.yml)
[](https://github.com/cnoe-io/agent-argocd/actions/workflows/unit-tests.yml)
[](https://github.com/cnoe-io/agent-argocd/actions/workflows/acp-docker-build.yml)
[](https://github.com/cnoe-io/agent-argocd/actions/workflows/a2a-docker-build.yml)
---
---
- 🤖 **ArgoCD 代理** 是基于 [LangGraph ReAct Agent](https://langchain-ai.github.io/langgraph/agents/agents/) 工作流和 [MCP 工具](https://modelcontextprotocol.io/introduction) 构建的 LLM 驱动代理。
- 🌐 **协议支持：** 与 [ACP](https://github.com/agntcy/acp-spec) 和 [A2A](https://github.com/google/A2A) 协议兼容，以便与外部用户客户端集成。
- 🛡️ **设计安全：** 强制执行 ArgoCD API 基于令牌的 RBAC，并支持外部身份验证以实现强访问控制。
- 🔌 **集成通信：** 使用 [langchain-mcp-adapters](https://github.com/langchain-ai/langchain-mcp-adapters) 在 LangGraph ReAct Agent 工作流中连接到 ArgoCD MCP 服务器。
- 🏭 **一流 MCP 服务器：** MCP 服务器由我们的第一方 [openapi-mcp-codegen](https://github.com/cnoe-io/openapi-mcp-codegen/tree/main) 实用程序生成，确保版本/API 兼容性和软件供应链完整性。
---
## 🚦 入门指南
### 1️⃣ 配置环境
- 确保您的 `.env` 文件按照 [cnoe-agent-utils 使用指南](https://github.com/cnoe-io/cnoe-agent-utils#-usage) 中的描述进行设置，具体取决于您的 LLM 提供商。
- 参考 [.env.example](.env.example) 作为示例。
**示例 `.env` 文件：**
```
LLM_PROVIDER=aws-bedrock
AGENT_NAME=ArgoCD
## ArgoCD 配置
ARGOCD_TOKEN=
ARGOCD_API_URL=
ARGOCD_VERIFY_SSL=true
## A2A 代理配置
A2A_HOST=localhost
A2A_PORT=8000
########### LLM 配置 ###########
# AWS 配置
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=
AWS_BEDROCK_MODEL_ID="us.amazon.nova-pro-v1:0"
AWS_BEDROCK_PROVIDER="amazon"
```
### 2️⃣ 启动代理（A2A 模式）
> **注意：**
> - 如果您无法访问 ArgoCD 服务器，请参阅下面的 [本地开发设置](#-pre-requisite-start-local-argocd-server) 部分，以快速启动本地 ArgoCD 实例并部署示例应用程序，然后再继续。
> - 如果您使用的是其他容器运行时，例如 `podman` 或 `ctr`，请在下面的命令中将 `docker` 替换为相应的实用程序。
使用您的 `.env` 文件在 Docker 容器中运行代理：
```bash
docker run -p 0.0.0.0:8000:8000 -it \
-v $(pwd)/.env:/app/.env \
ghcr.io/cnoe-io/agent-argocd:a2a-latest
```
### 3️⃣ 运行客户端
使用 [agent-chat-cli](https://github.com/cnoe-io/agent-chat-cli) 与代理交互：
```bash
uvx https://github.com/cnoe-io/agent-chat-cli.git a2a
```
## 快速演示
### AGNTCY ACP 演示
### Google A2A 演示
## 🏗️ 架构
```mermaid
flowchart TD
subgraph Client Layer
A[用户客户端 ACP/A2A]
end
subgraph Agent Transport Layer
B[AGNTCY ACP<br/>或<br/>Google A2A]
end
subgraph Agent Graph Layer
C[LangGraph ReAct Agent]
end
subgraph Tools/MCP Layer
D[Langchain MCP Adapter]
E[ArgoCD MCP 服务器]
F[ArgoCD API 服务器]
end
A --> B --> C
C --> D
D -.-> C
D --> E --> F --> E
```
---
## ✨ 功能
- 🤖 **LangGraph + LangChain MCP 适配器** 用于代理编排
- 🧠 **Azure OpenAI GPT-4o** 作为 LLM 后端
- 🔗 通过专用 [ArgoCD MCP 代理](https://github.com/cnoe-io/agent-argocd/tree/main/agent_argocd/protocol_bindings/mcp_server) 连接到 ArgoCD
- 🔄 **多协议支持：** 与 **ACP** 和 **A2A** 协议兼容，以实现灵活的集成和多代理编排
## 本地开发设置
### ▶️ [可选] 使用 kind 启动本地 ArgoCD 服务器
**注意：**
本部分假设您对 Kubernetes 概念和工具有一定的了解，因为在本地运行 ArgoCD 需要与 Kubernetes 集群和资源进行交互。
如果您没有现有的 ArgoCD 服务器，可以使用 [kind](https://kind.sigs.k8s.io/) 快速启动一个：
- **安装 KinD**
_参考：_ https://kind.sigs.k8s.io/docs/user/quick-start/#installing-from-release-binaries
- **创建 kind 集群：**
```bash
kind create cluster --name cnoe-argocd-agent
```
- **在 `argocd` 命名空间中安装 ArgoCD：**
```bash
kubectl create namespace argocd
```
```bash
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
```
- **暴露 ArgoCD API 服务器：**
等待所有 Pod 运行完毕并检查其状态：
```bash
kubectl get pods -A
```
```bash
kubectl port-forward svc/argocd-server -n argocd 8080:443
```
API 将在 `https://localhost:8080` 上可用。
- **获取 ArgoCD 管理员密码：**
```bash
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d && echo
```
- **（可选）安装 ArgoCD CLI：**
```bash
brew install argocd
# 或参见 https://argo-cd.readthedocs.io/en/stable/cli_installation/
```
#### 示例：使用 ArgoCD CLI 部署 Guestbook
> **注意：** 使用新的终端会话并继续在本地运行 ArgoCD，通过端口转发。
要使用 ArgoCD CLI 部署 [Guestbook](https://github.com/argoproj/argocd-example-apps/tree/master/guestbook) 演示应用程序，请按照以下步骤操作：
1. **登录到 ArgoCD：**
```bash
argocd login localhost:8080 --username admin --password <ARGOCD_ADMIN_PASSWORD> --insecure
```
2. **创建 Guestbook 应用程序：**
```bash
argocd app create guestbook \
--repo https://github.com/argoproj/argocd-example-apps.git \
--path guestbook \
--dest-server https://kubernetes.default.svc \
--dest-namespace default
```
3. **同步（部署）应用程序：**
```bash
argocd app sync guestbook
```
4. **检查应用程序状态：**
```bash
argocd app get guestbook
```
5. **生成 ArgoCD API 令牌：**
要以编程方式与 ArgoCD 交互，您需要一个 API 令牌。登录 CLI 后，运行：
```bash
kubectl -n argocd patch configmap argocd-cm --type merge -p '{"data":{"accounts.admin":"login,apiKey"}}'
```
```bash
kubectl -n argocd rollout restart deployment argocd-server
```
```bash
argocd account generate-token --account admin
```
复制输出的令牌并将其设置为 `.env` 文件中的 `ARGOCD_TOKEN`：
```
ARGOCD_TOKEN=
ARGOCD_API_URL=https://localhost:8080
ARGOCD_VERIFY_SSL=false
```
有关更多详细信息，请参见 [官方入门指南](https://argo-cd.readthedocs.io/en/stable/getting_started/#1-install-argo-cd).
### 1️⃣ 创建/更新 `.env`
- 确保您的 `.env` 文件按照 [cnoe-agent-utils 使用指南](https://github.com/cnoe-io/cnoe-agent-utils#-usage) 中的描述进行设置，具体取决于您的 LLM 提供商。
- 参考 [.env.example](.env.example) 作为示例。
### 2️⃣ 启动 A2A 代理
- **A2A 模式：**
```bash
make run-a2a
```
### 3️⃣ 运行 A2A 客户端
要在 **A2A 模式** 下与代理交互：
```bash
uvx https://github.com/cnoe-io/agent-chat-cli.git a2a
```
或
```bash
make run-a2a-client
```
**示例交互**
```
> 你的问题：你能帮我吗？
代理： 我可以帮助您管理 ArgoCD 中的应用程序，包括以下任务：
```
- **列出应用程序**：检索具有筛选选项的应用程序列表。
- **获取应用程序详细信息**：获取特定应用程序的详细信息。
- **创建应用程序**：在 ArgoCD 中创建新应用程序。
- **更新应用程序**：更新现有应用程序。
- **删除应用程序**：从 ArgoCD 中删除应用程序。
- **同步应用程序**：将应用程序同步到特定的 Git 修订版本。
- **获取用户信息**：检索当前用户信息。
- **获取 ArgoCD 设置**：访问服务器设置。
- **获取插件**：列出可用插件。
- **获取版本信息**：检索 ArgoCD API 服务器版本。
---
## 🧬 内部
- 🛠️ 使用 [`create_react_agent`](https://docs.langchain.com/langgraph/agents/react/) 进行工具调用
- 🔌 从 **ArgoCD MCP 服务器** （子模块）加载工具
- ⚡ 使用 `uv run` 启动 MCP 服务器，带有 `stdio` 传输
- 🕸️ 用于推理和动作路由的单节点 LangGraph
---
## 📁 项目结构
```text
agent_argocd
├── __main__.py
├── agent.py
├── graph.py
├── llm_factory.py
├── models.py
├── protocol_bindings
│ ├── __init__.py
│ ├── a2a_server
│ │ └── agent_executor.py
│ ├── acp_server
│ │ └── agent.json
│ └── mcp_server
│ ├── __init__.py
│ └── mcp_argocd
│ ├── __init__.py
│ ├── api
│ │ └── client.py
│ ├── models
│ │ └── base.py
│ ├── server.py
│ ├── tools
│ │ └── api_v1_applications.py
│ └── utils
│ └── __init__.py
└── state.py
```
---
## 🧩 MCP 子模块（ArgoCD 工具）
该项目使用根据 ArgoCD OpenAPI 规范使用我们的 [openapi-mcp-codegen](https://github.com/cnoe-io/openapi-mcp-codegen/tree/main/examples) 实用程序生成的 **第一方 MCP 模块**。生成的 MCP 服务器作为 `argocd_mcp/` 中的 Git 子模块包含。
所有与 ArgoCD 相关的 LangChain 工具由此 MCP 服务器实现，确保最新的 API 兼容性和供应链完整性。
## 评估
### 运行评估
此评估使用 [agentevals](https://github.com/langchain-ai/agentevals) 执行严格的轨迹匹配评估代理行为。要运行评估套件：
```bash
make evals
```
这将：
- 设置并激活 Python 虚拟环境
- 安装评估依赖项 (`agentevals`, `tabulate`, `pytest`)
- 对代理运行严格的轨迹匹配测试
#### 示例输出
```
=======================================
设置虚拟环境
=======================================
虚拟环境已存在。
=======================================
激活虚拟环境
=======================================
要手动激活 venv，请运行： source .venv/bin/activate
. .venv/bin/activate
运行代理严格轨迹匹配评估...
安装 agentevals 与 Poetry...
. .venv/bin/activate && uv add agentevals tabulate pytest
...
set -a && . .env && set +a && uv run evals/strict_match/test_strict_match.py
...
测试 ID：argocd_agent_1
提示：显示 argocd 版本
参考轨迹：[['__start__'， 'agent_argocd']]
注意：显示 ArgoCD 服务器版本。
...
结果：
{'score': True}
...
```
#### 评估结果
[最新严格匹配评估结果](evals/strict_match/README.md)
---
## 📜 许可证
Apache 2.0（参见 [LICENSE](./LICENSE)）
---
## 👥 维护者
参见 [MAINTAINERS.md](MAINTAINERS.md)
- 通过 PR 或问题欢迎贡献！
---
## 🙏 致谢
- [LangGraph](https://github.com/langchain-ai/langgraph) 和 [LangChain](https://github.com/langchain-ai/langchain) 用于代理编排框架。
- [langchain-mcp-adapters](https://github.com/langchain-ai/langchain-mcp-adapters) 用于 MCP 集成。
- [AGNTCY 代理连接协议（ACP）](https://docs.agntcy.org/pages/syntactic_sdk/connect.html)
- [AGNTCY 代理网关协议（AGP）](https://docs.agntcy.org/pages/messaging_sdk/agp-howto.html)
- [AGNTCY 工作流服务器管理器（WFSM）](https://github.com/agntcy/workflow-srv-mgr) 用于部署和编排。
- [模型上下文协议（MCP）](https://modelcontextprotocol.io/) 用于协议规范。
- [Google A2A](https://github.com/google/A2A/tree/main)
- 持续支持和贡献的开源社区。
