agent-argocd

# 🚀 ArgoCD AI Agent [](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 Agent** is an LLM-powered agent built using the [LangGraph ReAct Agent](https://langchain-ai.github.io/langgraph/agents/agents/) workflow and [MCP tools](https://modelcontextprotocol.io/introduction). - 🌐 **Protocol Support:** Compatible with [ACP](https://github.com/agntcy/acp-spec) and [A2A](https://github.com/google/A2A) protocols for integration with external user clients. - 🛡️ **Secure by Design:** Enforces ArgoCD API token-based RBAC and supports external authentication for strong access control. - 🔌 **Integrated Communication:** Uses [langchain-mcp-adapters](https://github.com/langchain-ai/langchain-mcp-adapters) to connect with the ArgoCD MCP server within the LangGraph ReAct Agent workflow. - 🏭 **First-Party MCP Server:** The MCP server is generated by our first-party [openapi-mcp-codegen](https://github.com/cnoe-io/openapi-mcp-codegen/tree/main) utility, ensuring version/API compatibility and software supply chain integrity. --- ## 🚦 Getting Started ### 1️⃣ Configure Environment - Ensure your `.env` file is set up as described in the [cnoe-agent-utils usage guide](https://github.com/cnoe-io/cnoe-agent-utils#-usage) based on your LLM Provider. - Refer to [.env.example](.env.example) as an example. **Example .env file:** ``` LLM_PROVIDER=aws-bedrock AGENT_NAME=ArgoCD ## ArgoCD Configuration ARGOCD_TOKEN= ARGOCD_API_URL= ARGOCD_VERIFY_SSL=true ## A2A Agent Configuration A2A_HOST=localhost A2A_PORT=8000 ########### LLM Configuration ########### # AWS Configuration 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️⃣ Start the Agent (A2A Mode) > **Note:** > - If you don't have access to an ArgoCD server, see the [Local Development Setup](#-pre-requisite-start-local-argocd-server) section below to quickly spin up a local ArgoCD instance and deploy a sample app before proceeding. > - If you are using a different container runtime such as `podman` or `ctr`, please substitute `docker` with the respective utility in the commands below. Run the agent in a Docker container using your `.env` file: ```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️⃣ Run the Client Use the [agent-chat-cli](https://github.com/cnoe-io/agent-chat-cli) to interact with the agent: ```bash uvx https://github.com/cnoe-io/agent-chat-cli.git a2a ``` ## Quick Demos ### AGNTCY ACP Demo  ### Google A2A Demo  ## 🏗️ Architecture ```mermaid flowchart TD subgraph Client Layer A[User Client ACP/A2A] end subgraph Agent Transport Layer B[AGNTCY ACP<br/>or<br/>Google A2A] end subgraph Agent Graph Layer C[LangGraph ReAct Agent] end subgraph Tools/MCP Layer D[Langchain MCP Adapter] E[ArgoCD MCP Server] F[ArgoCD API Server] end A --> B --> C C --> D D -.-> C D --> E --> F --> E ``` --- ## ✨ Features - 🤖 **LangGraph + LangChain MCP Adapter** for agent orchestration - 🧠 **Azure OpenAI GPT-4o** as the LLM backend - 🔗 Connects to ArgoCD via a dedicated [ArgoCD MCP agent](https://github.com/cnoe-io/agent-argocd/tree/main/agent_argocd/protocol_bindings/mcp_server) - 🔄 **Multi-protocol support:** Compatible with both **ACP** and **A2A** protocols for flexible integration and multi-agent orchestration ## Local Development Setup ### ▶️ [Optional] Start local ArgoCD Server with kind **Note:** This section assumes you have basic familiarity with Kubernetes concepts and tools, as running ArgoCD locally requires interacting with Kubernetes clusters and resources. If you don't have an existing ArgoCD server, you can quickly spin one up using [kind](https://kind.sigs.k8s.io/): - **Install KinD** _Reference:_ https://kind.sigs.k8s.io/docs/user/quick-start/#installing-from-release-binaries - **Create a kind cluster:** ```bash kind create cluster --name cnoe-argocd-agent ``` - **Install ArgoCD in the `argocd` namespace:** ```bash kubectl create namespace argocd ``` ```bash kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml ``` - **Expose the ArgoCD API server:** Wait until all the pods are running by checking their status: ```bash kubectl get pods -A ``` ```bash kubectl port-forward svc/argocd-server -n argocd 8080:443 ``` The API will be available at `https://localhost:8080`. - **Get the ArgoCD admin password:** ```bash kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d && echo ``` - **(Optional) Install ArgoCD CLI:** ```bash brew install argocd # or see https://argo-cd.readthedocs.io/en/stable/cli_installation/ ``` #### Example: Deploying Guestbook via ArgoCD CLI > **Note:** Use a new terminal session and continue to run ArgoCD locally via port forwarding. To deploy the [Guestbook](https://github.com/argoproj/argocd-example-apps/tree/master/guestbook) demo application using the ArgoCD CLI, follow these steps: 1. **Login to ArgoCD:** ```bash argocd login localhost:8080 --username admin --password <ARGOCD_ADMIN_PASSWORD> --insecure ``` 2. **Create the Guestbook application:** ```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. **Sync (deploy) the application:** ```bash argocd app sync guestbook ``` 4. **Check application status:** ```bash argocd app get guestbook ``` 5. **Generate an ArgoCD API Token:** To interact programmatically with ArgoCD, you need an API token. After logging in with the CLI, run: ```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 ``` Copy the output token and set it as `ARGOCD_TOKEN` in your `.env` file. ``` ARGOCD_TOKEN= ARGOCD_API_URL=https://localhost:8080 ARGOCD_VERIFY_SSL=false ``` For more details, see the [official getting started guide](https://argo-cd.readthedocs.io/en/stable/getting_started/#1-install-argo-cd). ### 1️⃣ Create/Update `.env` - Ensure your `.env` file is set up as described in the [cnoe-agent-utils usage guide](https://github.com/cnoe-io/cnoe-agent-utils#-usage) based on your LLM Provider. - Refer to [.env.example](.env.example) as an example. ### 2️⃣ Start A2A Agent - **A2A Mode:** ```bash make run-a2a ``` ### 3️⃣ Run the A2A Client To interact with the agent in **A2A mode**: ```bash uvx https://github.com/cnoe-io/agent-chat-cli.git a2a ``` or ```bash make run-a2a-client ``` **Example Interaction** ``` > Your Question: how can you help? Agent: I can assist you with managing applications in ArgoCD, including tasks such as: ``` - **Listing Applications**: Retrieve a list of applications with filtering options. - **Getting Application Details**: Fetch detailed information about a specific application. - **Creating Applications**: Create new applications in ArgoCD. - **Updating Applications**: Update existing applications. - **Deleting Applications**: Remove applications from ArgoCD. - **Syncing Applications**: Synchronize applications to a specific Git revision. - **Getting User Info**: Retrieve information about the current user. - **Getting ArgoCD Settings**: Access server settings. - **Getting Plugins**: List available plugins. - **Getting Version Information**: Retrieve ArgoCD API server version. --- ## 🧬 Internals - 🛠️ Uses [`create_react_agent`](https://docs.langchain.com/langgraph/agents/react/) for tool-calling - 🔌 Tools loaded from the **ArgoCD MCP server** (submodule) - ⚡ MCP server launched via `uv run` with `stdio` transport - 🕸️ Single-node LangGraph for inference and action routing --- ## 📁 Project Structure ```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 Submodule (ArgoCD Tools) This project uses a **first-party MCP module** generated from the ArgoCD OpenAPI specification using our [openapi-mcp-codegen](https://github.com/cnoe-io/openapi-mcp-codegen/tree/main/examples) utility. The generated MCP server is included as a git submodule in `argocd_mcp/`. All ArgoCD-related LangChain tools are defined by this MCP server implementation, ensuring up-to-date API compatibility and supply chain integrity. ## Evals ### Running Evals This evaluation uses [agentevals](https://github.com/langchain-ai/agentevals) to perform strict trajectory match evaluation of the agent's behavior. To run the evaluation suite: ```bash make evals ``` This will: - Set up and activate the Python virtual environment - Install evaluation dependencies (`agentevals`, `tabulate`, `pytest`) - Run strict trajectory matching tests against the agent #### Example Output ``` ======================================= Setting up the Virtual Environment ======================================= Virtual environment already exists. ======================================= Activating virtual environment ======================================= To activate venv manually, run: source .venv/bin/activate . .venv/bin/activate Running Agent Strict Trajectory Matching evals... Installing agentevals with Poetry... . .venv/bin/activate && uv add agentevals tabulate pytest ... set -a && . .env && set +a && uv run evals/strict_match/test_strict_match.py ... Test ID: argocd_agent_1 Prompt: show argocd version Reference Trajectories: [['__start__', 'agent_argocd']] Note: Shows the version of the ArgoCD Server Version. ... Results: {'score': True} ... ``` #### Evaluation Results [Latest Strict Match Eval Results](evals/strict_match/README.md) --- ## 📜 License Apache 2.0 (see [LICENSE](./LICENSE)) --- ## 👥 Maintainers See [MAINTAINERS.md](MAINTAINERS.md) - Contributions welcome via PR or issue! --- ## 🙏 Acknowledgements - [LangGraph](https://github.com/langchain-ai/langgraph) and [LangChain](https://github.com/langchain-ai/langchain) for agent orchestration frameworks. - [langchain-mcp-adapters](https://github.com/langchain-ai/langchain-mcp-adapters) for MCP integration. - [AGNTCY Agent Connect Protocol(ACP)](https://docs.agntcy.org/pages/syntactic_sdk/connect.html) - [AGNTCY Agent Gateway Protocol(AGP)](https://docs.agntcy.org/pages/messaging_sdk/agp-howto.html) - [AGNTCY Workflow Server Manager (WFSM)](https://github.com/agntcy/workflow-srv-mgr) for deployment and orchestration. - [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the protocol specification. - [Google A2A](https://github.com/google/A2A/tree/main) - The open source community for ongoing support and contributions.