Kagent Bhg

kagent-bhg-kagent配置库

此存储库包含带有GitOps部署自动化的KAgent代理和MCP服务器定义。

概述

此存储库使用GitOps原则来管理KAgent代理和MCP服务器。更改已推送到 main 分支通过ArgoCD自动部署到集群。

存储库结构

.
├── README.md
├── manifests/
│   ├── agents/              # Agent definitions
│   │   ├── genetics-game-designer.yaml
│   │   ├── genetics-sim-engineer.yaml
│   │   ├── genetics-devops.yaml
│   │   └── ...
│   ├── mcp-servers/         # RemoteMCPServer definitions
│   │   ├── kagent-tool-server.yaml
│   │   ├── github-mcp.yaml
│   │   └── ...
│   └── model-configs/       # ModelConfig definitions
│       ├── openai-gpt-4.yaml
│       └── ...
├── templates/              # Templates for creating new resources
│   ├── agent-template.yaml
│   ├── mcp-server-template.yaml
│   └── model-config-template.yaml
└── .github/
    └── workflows/
        └── deploy.yaml     # CI/CD pipeline

快速开始

1.连接到ArgoCD

这种bhg存储库包括一个监视此存储库的ArgoCD应用程序：

cd ../kind-bhg
kubectl apply -f manifests/argocd/kagent-bhg-app.yaml

2.进行更改

在中编辑代理或MCP服务器定义 manifests/ 目录：

# Edit an agent
vim manifests/agents/my-agent.yaml

# Commit and push
git add manifests/agents/my-agent.yaml
git commit -m "feat: update my-agent configuration"
git push origin main

3.自动部署

ArgoCD将自动：

1. 检测变化
2. 将清单同步到集群
3. 部署更新的代理/MCP服务器

创建新资源

创建新代理

1. 复制模板：

cp templates/agent-template.yaml manifests/agents/my-new-agent.yaml

1. 编辑代理定义：

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: my-new-agent
  namespace: kagent
spec:
  type: Declarative
  description: Description of what this agent does
  declarative:
    modelConfig: openai-gpt-4
    stream: true
    tools:
      - type: McpServer
        mcpServer:
          apiGroup: kagent.dev
          kind: RemoteMCPServer
          name: kagent-tool-server
          toolNames:
            - k8s_apply_manifest
            - helm_upgrade
    systemMessage: |-
      You are an AI agent that...
      
      Your responsibilities include:
      - Task 1
      - Task 2

1. 承诺并推动：

git add manifests/agents/my-new-agent.yaml
git commit -m "feat: add my-new-agent"
git push origin main

创建新的MCP服务器

1. 复制模板：

cp templates/mcp-server-template.yaml manifests/mcp-servers/my-mcp-server.yaml

1. 编辑MCP服务器定义：

apiVersion: kagent.dev/v1alpha2
kind: RemoteMCPServer
metadata:
  name: my-mcp-server
  namespace: kagent
spec:
  description: Description of tools provided
  protocol: STREAMABLE_HTTP
  url: http://my-mcp-server.kagent:8080/mcp

1. 提交并推动（与上述相同）

代理商指南

最佳实践

1. 清晰的描述：使代理描述具体可行
2. 重点责任：每个代理人都应该有一个明确、专注的目的
3. 合适的工具：仅包括代理实际需要的工具
4. 系统消息：提供明确的指示和限制
5. 命名约定：使用带连字符的小写字母（例如。， my-agent-name)

系统消息结构

良好的系统信息包括：

• 明确的角色定义
• 具体责任
• 显式约束
• 输出格式要求
• 示例（如果有用）

例子：

systemMessage: |-
  You are a Kubernetes deployment specialist.
  
  Responsibilities:
  - Review deployment manifests for best practices
  - Suggest security improvements
  - Validate resource requirements
  
  Constraints:
  - Only suggest changes, don't automatically apply them
  - Always explain your reasoning
  - Follow Kubernetes security best practices
  
  Output format:
  - Start with a summary
  - List specific issues found
  - Provide recommended changes with YAML snippets

MCP服务器指南

可用的MCP服务器

群集中的当前MCP服务器：

1. kagent工具服务器 -Kubernetes和Helm操作

- 工具：k8s_apply_manifest、k8s_create_resource、k8_sdelete_resource、helm_upgrade、helm_list_releases

1. 卡根特·格拉法纳·麦克普 -Grafana/监控查询

- 工具：Grafana相关操作

1. kagent查询文档 -文档查询

- 工具：文档搜索和检索

添加外部MCP服务器

要添加新的MCP服务器，请执行以下操作：

1. 将MCP服务器部署到集群
2. 创建暴露MCP端点的服务
3. 在此存储库中创建RemoteMCPServer资源
4. 在代理定义中引用它

CI/CD管道

GitHub操作工作流(.github/workflows/deploy.yaml)执行：

1. 验证：验证YAML语法和Kubernetes资源定义
2. 测试：对代理配置运行基本测试
3. 部署：与ArgoCD同步（通过ArgoCD自己的同步自动）

手动同步

要手动触发同步，请执行以下操作：

# Using ArgoCD CLI
argocd app sync kagent-bhg

# Using kubectl
kubectl patch app kagent-bhg -n argocd --type merge -p '{"operation":{"initiatedBy":{"username":"manual"},"sync":{}}}'

监控

检查部署状态

# Via ArgoCD UI
kubectl port-forward svc/argocd-server -n argocd 8080:443
# Visit https://localhost:8080

# Via ArgoCD CLI
argocd app get kagent-bhg

# Check agent status
kubectl get agents -n kagent

查看代理日志

# List agents
kubectl get agents -n kagent

# Get agent pod
kubectl get pods -n kagent -l kagent.dev/agent=my-agent-name

# View logs
kubectl logs -n kagent -l kagent.dev/agent=my-agent-name

故障排除

代理未部署

# Check ArgoCD application status
argocd app get kagent-bhg

# Check for sync errors
kubectl describe app kagent-bhg -n argocd

# Check agent resource
kubectl describe agent my-agent-name -n kagent

代理不工作

# Check agent pod
kubectl get pods -n kagent -l kagent.dev/agent=my-agent-name

# Check logs
kubectl logs -n kagent -l kagent.dev/agent=my-agent-name

# Check model config
kubectl get modelconfig -n kagent

# Verify API keys
kubectl get secrets -n kagent | grep api-key

MCP服务器不可用

# Check MCP server resource
kubectl get remotemcpserver -n kagent

# Describe the MCP server
kubectl describe remotemcpserver my-mcp-server -n kagent

# Check if service exists
kubectl get svc -n kagent | grep mcp

# Test connectivity
kubectl run -it --rm debug --image=curlimages/curl --restart=Never -- curl http://my-mcp-server.kagent:8080/health

安全

秘密管理

• 切勿将机密提交到此存储库
• 使用Kubernetes Secrets处理敏感数据
• 代理配置中的参考机密
• 考虑使用密封秘密或外部秘密运算符

API密钥

API密钥应存储为Kubernetes机密：

# Create OpenAI API key secret
kubectl create secret generic openai-api-key -n kagent \
  --from-literal=api-key="your-api-key"

# Reference in ModelConfig
apiVersion: kagent.dev/v1alpha2
kind: ModelConfig
metadata:
  name: openai-gpt-4
  namespace: kagent
spec:
  provider: openai
  model: gpt-4-turbo
  apiKeySecret:
    name: openai-api-key
    key: api-key

贡献

看 贡献.md 作为指导方针。

许可证

麻省理工学院