What is Agent Argocd

agent-argocd is an ArgoCD AI Agent powered by a first-party MCP Server utilizing OpenAPI Codegen, LangGraph, and LangChain MCP Adapters. It supports various agent transport protocols including AGNTCY ACP, Google A2A, and MCP Server.

Use cases

Use cases for agent-argocd include automating deployment processes in Kubernetes, integrating AI-driven decision-making in CI/CD workflows, and enhancing application management through improved API interactions.

How to use

To use agent-argocd, you need to set up the MCP Server and configure the agent with the appropriate transport protocol. Detailed instructions can be found in the README documentation, which guides users through installation and configuration steps.

Key features

Key features of agent-argocd include support for multiple transport protocols, integration with OpenAPI Codegen for API generation, and the ability to leverage AI capabilities through LangGraph and LangChain MCP Adapters.

Where to use

agent-argocd can be used in cloud-native environments, DevOps pipelines, and any application that requires continuous delivery and deployment automation, particularly those utilizing ArgoCD.

🚀 ArgoCD AI Agent

• 🤖 ArgoCD Agent is an LLM-powered agent built using the LangGraph ReAct Agent workflow and ArgoCD MCP Server.
• 🌐 Protocol Support: Compatible with A2A protocol for integration with external user clients.
• 🛡️ Secure by Design: Enforces ArgoCD API token-based RBAC and supports secondary external authentication for strong access control.
• 🏭 MCP Server: The MCP server is generated by our first-party openapi-mcp-codegen utility, ensuring version/API compatibility and software supply chain integrity.
• 🔌 MCP Tools: Uses langchain-mcp-adapters to glue the tools from ArgoCD MCP server to LangGraph ReAct Agent Graph.

🚦 Getting Started

1️⃣ Environment Setup

• Copy and configure your .env based on your LLM provider.
• Use .env.example and refer to the cnoe-agent-utils guide.

2️⃣ Start the Agent (A2A Mode)

Note: a2a-stable is the latest stable version of the agent. For production use cases, consider using a pinned version.

docker run -p 0.0.0.0:8000:8000 -it \
  -v $(pwd)/.env:/app/.env \
  ghcr.io/cnoe-io/agent-argocd:a2a-stable

💡 Don’t have ArgoCD running? See Local Dev Setup.

3️⃣ Run the A2A Client

Pick one of the following methods:

• Docker:

  docker run -it --network=host ghcr.io/cnoe-io/agent-chat-cli:stable
  

• Python CLI:

  uvx https://github.com/cnoe-io/agent-chat-cli.git a2a
  

🏗️ Architecture

System Diagram

flowchart TD
  subgraph Client Layer
    A[User Client A2A]
  end
  subgraph Agent Transport Layer
    B[Google A2A]
  end
  subgraph Agent Graph Layer
    C[LangGraph ReAct Agent]
  end
  subgraph Tools Layer
    D[LangChain MCP Adapter]
    E[ArgoCD MCP Server]
    F[ArgoCD API Server]
  end

  A --> B --> C --> D --> E --> F
  F --> E --> D --> C --> B --> A

Sequence Diagram

sequenceDiagram
  participant User
  participant A2A
  participant Agent as LangGraph ReAct Agent
  participant LLM
  participant MCP as ArgoCD MCP Server
  participant APIServer as ArgoCD API Server

  note over Agent,MCP: 🛠️ Agent Setup Phase
  rect rgb(245, 245, 220)
    Agent->>MCP: Get Tools
    Agent->>LLM: Bind Tools
  end

  rect rgb(220, 232, 243)
    note over User,A2A: 🧑‍💻 User Input Phase
    User->>A2A: Send request
    A2A->>Agent: Forward to LangGraph Agent

    note over Agent,LLM: 🧠 Agent Reasoning & Tool Selection
    Agent->>LLM: [Reason] User Input
    LLM-->>Agent: [Act] Excecute MCP Tool

    note over MCP,APIServer: 🛠️ API Invocation Phase
    Agent->>MCP: Invoke tool
    MCP->>APIServer: Call API
    APIServer-->>MCP: Return data
    MCP-->>Agent: Return data

    note over Agent,LLM: 🧠 Agent Reasoning & Output Structuring
    Agent->>LLM: Input API result data for further ReAct loop
    LLM-->>Agent: Return Structured Output

    note over User,A2A: 📤 User Output Phase
    Agent-->>A2A: Respond with Structured Output
    A2A-->>User: Respond to user (Non-stream or streaming)
  end

⚙️ Local Development Setup

Use this setup to test the agent against a local ArgoCD instance.

▶️ Start ArgoCD with kind cluster

Note: KinD (Kubernetes in Docker) is a tool for running local Kubernetes clusters using Docker.
For detailed setup instructions, refer to the KinD documentation. Below is a quickstart to launch a local cluster and install ArgoCD:

kind create cluster --name cnoe-argocd-agent
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
kubectl port-forward svc/argocd-server -n argocd 8080:443

kind create cluster --name cnoe-argocd-agent
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
kubectl port-forward svc/argocd-server -n argocd 8080:443

🛂 Retrieve Admin Credentials

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d && echo

📦 Install CLI (Optional)

brew install argocd

🚀 Deploy Guestbook Example

argocd login localhost:8080 --username admin --password <password> --insecure
argocd app create guestbook \
  --repo https://github.com/argoproj/argocd-example-apps.git \
  --path guestbook \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default
argocd app sync guestbook

🔑 Get API Token

kubectl -n argocd patch configmap argocd-cm --type merge -p '{"data":{"accounts.admin":"login,apiKey"}}'
kubectl -n argocd rollout restart deployment argocd-server
argocd account generate-token --account admin

Add to your .env:

ARGOCD_TOKEN=<your_token>
ARGOCD_API_URL=https://localhost:8080
ARGOCD_VERIFY_SSL=false

🛠️ Common Development Tasks

1️⃣ Run A2A Agent Locally (without Docker)

• Makefile Target: run-a2a
• What it does:
  • Ensures your .env file exists.
  • Activates the Python virtual environment.
  • Loads environment variables from .env.
  • Runs the agent using uv (a fast Python runner) on the port specified by A2A_PORT in your .env (defaults to 8000 if not set).

2️⃣ Build Local Docker Image

• Makefile Target: build-docker-a2a
• What it does:
  • Builds a Docker image for the A2A agent using build/Dockerfile.a2a.
  • Tags the image as agent-<name>:a2a-latest (e.g., agent-argocd:a2a-latest).

3️⃣ Run the Agent in Docker

• Makefile Target: run-docker-a2a
• What it does:
  • Reads A2A_PORT and A2A_AGENT_IMAGE from .env (uses defaults if not set).
  • Runs the Docker image, mapping the chosen port to container port 8000.
  • Mounts your .env file into the container for configuration.

⚡ Typical Workflow & Gotchas

• Ensure your .env file exists and is up to date.
• If you change code, rebuild the Docker image before running again.
• The Docker container uses port 8000 internally; you can change the host port via A2A_PORT in .env.

🧩 MCP Server

This project includes a first-party MCP server generated from ArgoCD’s OpenAPI specification using the openapi-mcp-codegen utility.

🧪 Evaluations

We use agentevals to verify agent behavior with strict trajectory matching.

Run Evals

make evals

This will:

• Activate the Python virtual environment
• Install test dependencies
• Run strict-match tests against the agent

👉 See results in evals/strict_match/README.md

📜 License

Apache 2.0 – see LICENSE

👥 Maintainers

See MAINTAINERS.md
Contributions welcome via issues and PRs!

🙏 Acknowledgements

• LangGraph
• LangChain
• langchain-mcp-adapters
• Model Context Protocol (MCP)
• Google A2A
• AGNTCY Slim
• OSS contributors & community!