zhanggangyong/agent_management
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 新增外部工具 API 及回调功能（计费）

Browse Source 
主要更新:
- 新增 external_tool_api.py: 外部工具管理 API
- 新增 tool_storage.py: 工具存储管理器
- 新增回调功能用于计费 (agent_callback_utils)
- 支持多工具创建 Agent
- 新增 CI/CD 构建状态查询 API
- 新增部署信息查询 API
- 更新文档 (EXTERNAL_TOOL_API.md v2.0)
- 更新 Dockerfile 添加新模块
- 更新 app.py 集成外部工具路由
This commit is contained in:
zhanggangyong
2026-01-29 12:00:16 +00:00
parent 4b09912806
commit 8cb166fb58
12 changed files with 3777 additions and 442 deletions
Download Patch File Download Diff File Expand all files Collapse all files
k8s/README.md
+414
View File
@@ -0,0 +1,414 @@
# Agent Manager Kubernetes部署文档
## 概述
本文档说明如何在Azure Kubernetes Service (AKS)上部署Agent Manager服务。
## 前提条件
1. **Azure资源**
- Azure订阅
- AKS集群
- Azure Container Registry (ACR)
- Azure DNS Zone（用于自动配置域名）
2. **本地工具**
- `kubectl` (Kubernetes命令行工具)
- `az` (Azure CLI)
- Docker (用于构建镜像)
3. **权限要求**
- AKS集群的管理员权限
- ACR的推送权限
- DNS Zone的管理权限
## 部署步骤
### 1. 配置Azure凭据
#### 1.1 创建Service Principal（如果还没有）
```bash
# 创建Service Principal
az ad sp create-for-rbac \
--name "agent-manager-sp" \
--role contributor \
--scopes /subscriptions/{subscription-id}
# 输出示例：
# {
# "appId": "c5ba26db-f180-425f-bac3-93708d853988",
# "displayName": "agent-manager-sp",
# "password": "ydt8Q~...",
# "tenant": "263c3ff6-1be5-4141-8308-b188464fb297"
# }
```
#### 1.2 配置DNS权限（重要！⚠️）
**Agent Manager需要DNS Zone Contributor权限才能为创建的agent自动配置域名。**
使用提供的脚本配置DNS权限：
```bash
# 方法1：使用自动化脚本（推荐）
bash scripts/setup_dns_permissions.sh
# 方法2：手动配置
AZURE_CLIENT_ID="your-service-principal-app-id"
AZURE_SUBSCRIPTION_ID="your-subscription-id"
AZURE_RESOURCE_GROUP="your-resource-group"
AZURE_DNS_ZONE="your-dns-zone.com"
DNS_ZONE_ID="/subscriptions/$AZURE_SUBSCRIPTION_ID/resourceGroups/$AZURE_RESOURCE_GROUP/providers/Microsoft.Network/dnsZones/$AZURE_DNS_ZONE"
az role assignment create \
--assignee $AZURE_CLIENT_ID \
--role "DNS Zone Contributor" \
--scope $DNS_ZONE_ID
```
验证权限：
```bash
az role assignment list \
--assignee $AZURE_CLIENT_ID \
--scope $DNS_ZONE_ID \
--output table
```
#### 1.3 更新Kubernetes Secret
编辑 `k8s/agent-manager-secret.yaml`：
```yaml
apiVersion: v1
kind: Secret
metadata:
name: agent-manager-secret
namespace: agent-manager
type: Opaque
stringData:
AZURE_TENANT_ID: "263c3ff6-1be5-4141-8308-b188464fb297"
AZURE_CLIENT_ID: "c5ba26db-f180-425f-bac3-93708d853988"
AZURE_CLIENT_SECRET: "your-client-secret"
AZURE_SUBSCRIPTION_ID: "45d7a360-af09-40fc-9afc-56dc475245ec"
AZURE_RESOURCE_GROUP: "taiji-ai-v0"
AZURE_DNS_ZONE: "taijiagnet.com"
```
### 2. 配置ACR访问
创建ACR secret：
```bash
# 获取ACR登录服务器
ACR_NAME="your-acr-name"
ACR_LOGIN_SERVER="${ACR_NAME}.azurecr.io"
# 创建Docker registry secret
kubectl create secret docker-registry acr-secret \
--namespace agent-manager \
--docker-server=$ACR_LOGIN_SERVER \
--docker-username=$AZURE_CLIENT_ID \
--docker-password=$AZURE_CLIENT_SECRET
```
或使用脚本：
```bash
bash k8s/create-acr-secret.sh
```
### 3. 构建和推送镜像
```bash
# 构建镜像
docker build -t $ACR_LOGIN_SERVER/agent-manager:latest .
# 登录ACR
az acr login --name $ACR_NAME
# 推送镜像
docker push $ACR_LOGIN_SERVER/agent-manager:latest
```
### 4. 部署到Kubernetes
```bash
# 创建命名空间
kubectl apply -f k8s/agent-manager-namespace.yaml
# 创建RBAC（ServiceAccount、Role、RoleBinding）
kubectl apply -f k8s/agent-manager-rbac.yaml
# 创建Secret（Azure凭据）
kubectl apply -f k8s/agent-manager-secret.yaml
# 创建ACR Secret
kubectl apply -f k8s/acr-secret.yaml
# 创建ConfigMap（可选）
kubectl apply -f k8s/agent-manager-configmap.yaml
# 创建Deployment
kubectl apply -f k8s/agent-manager-deployment.yaml
# 创建Service（LoadBalancer）
kubectl apply -f k8s/agent-manager-service.yaml
```
或使用一键部署脚本：
```bash
bash k8s/deploy.sh
```
### 5. 验证部署
```bash
# 检查Pod状态
kubectl get pods -n agent-manager
# 检查Service和外网IP
kubectl get svc -n agent-manager
# 查看日志
kubectl logs -n agent-manager deployment/agent-manager
# 测试健康检查
AGENT_MANAGER_IP=$(kubectl get svc agent-manager -n agent-manager -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
curl http://$AGENT_MANAGER_IP/
```
### 6. 测试Agent创建
```bash
# 创建测试agent
curl -X POST http://$AGENT_MANAGER_IP/agents \
-H "Content-Type: application/json" \
-d '{
"name": "test-agent",
"template": "echo_agent",
"framework": "API",
"config": {
"user_id": "test-user"
}
}'
# 检查返回结果应包含：
# - external_ip: 外网IP地址
# - domain: 自动配置的域名 (test-agent.taijiagnet.com)
# - domain_url: 域名访问地址
# - recommended: 推荐访问地址（域名）
# 查看agent状态
curl http://$AGENT_MANAGER_IP/agents/test-agent/status
# 测试域名访问
curl http://test-agent.taijiagnet.com/
# 清理测试agent
curl -X DELETE http://$AGENT_MANAGER_IP/agents/test-agent
```
## 目录结构
```
k8s/
├── README.md # 本文档
├── agent-manager-namespace.yaml # Namespace定义
├── agent-manager-rbac.yaml # RBAC配置（ServiceAccount、Role等）
├── agent-manager-secret.yaml # Azure凭据Secret
├── agent-manager-configmap.yaml # 配置文件ConfigMap
├── agent-manager-deployment.yaml # Deployment定义
├── agent-manager-service.yaml # LoadBalancer Service定义
├── acr-secret.yaml # ACR访问Secret
├── create-acr-secret.sh # 创建ACR Secret脚本
└── deploy.sh # 一键部署脚本
```
## 常见问题
### Q1: Agent创建后没有返回域名信息
**症状：** 创建agent时返回外网IP但没有`domain`字段。
**原因：** Service Principal缺少DNS Zone的写权限。
**解决方案：**
```bash
# 运行DNS权限配置脚本
bash scripts/setup_dns_permissions.sh
# 或手动分配权限（见上文"配置DNS权限"部分）
```
详细信息见：`docs/DNS_ISSUE_FIX_REPORT.md`
### Q2: Pod启动失败，提示ImagePullBackOff
**原因：** 无法从ACR拉取镜像。
**解决方案：**
1. 检查ACR secret是否正确创建
2. 验证Service Principal有ACR的pull权限
3. 确认镜像名称和标签正确
```bash
# 检查ACR secret
kubectl get secret acr-secret -n agent-manager
# 重新创建ACR secret
bash k8s/create-acr-secret.sh
```
### Q3: LoadBalancer IP一直处于Pending状态
**原因：** AKS集群配置或云提供商问题。
**解决方案：**
1. 检查AKS集群是否支持LoadBalancer
2. 查看Service事件：`kubectl describe svc agent-manager -n agent-manager`
3. 确认Azure订阅有足够的配额
### Q4: 如何更新部署
```bash
# 方法1：修改YAML文件后重新应用
kubectl apply -f k8s/agent-manager-deployment.yaml
# 方法2：更新镜像
kubectl set image deployment/agent-manager \
agent-manager=your-acr.azurecr.io/agent-manager:new-tag \
-n agent-manager
# 方法3：编辑Deployment
kubectl edit deployment agent-manager -n agent-manager
# 查看滚动更新状态
kubectl rollout status deployment/agent-manager -n agent-manager
```
### Q5: 如何查看日志
```bash
# 查看所有Pod日志
kubectl logs -n agent-manager -l app=agent-manager
# 查看特定Pod日志
kubectl logs -n agent-manager <pod-name>
# 实时跟踪日志
kubectl logs -n agent-manager -l app=agent-manager -f
# 查看前一个容器的日志（如果Pod重启过）
kubectl logs -n agent-manager <pod-name> --previous
```
## 监控和维护
### 资源使用
```bash
# 查看Pod资源使用
kubectl top pods -n agent-manager
# 查看Node资源使用
kubectl top nodes
```
### 扩缩容
```bash
# 手动扩容
kubectl scale deployment agent-manager \
--replicas=3 \
-n agent-manager
# 自动扩缩容（HPA）
kubectl autoscale deployment agent-manager \
--cpu-percent=80 \
--min=2 \
--max=10 \
-n agent-manager
```
### 健康检查
Agent Manager提供以下健康检查端点：
- `GET /` - 基本健康检查
- `GET /templates` - 模板列表（验证数据库连接）
- `GET /agents` - Agent列表（验证K8s连接）
## 安全最佳实践
1. **Secret管理**
- 不要将Secret提交到版本控制
- 使用Azure Key Vault或Kubernetes Secrets加密
- 定期轮换凭据
2. **RBAC**
- 使用最小权限原则
- 为不同环境使用不同的Service Principal
- 定期审计权限分配
3. **网络安全**
- 考虑使用Private LoadBalancer
- 配置Network Policy限制Pod间通信
- 使用Ingress Controller配置TLS
4. **镜像安全**
- 定期扫描镜像漏洞
- 使用最新的基础镜像
- 不要在镜像中包含敏感信息
## 故障排查
### 诊断命令
```bash
# 检查所有资源
kubectl get all -n agent-manager
# 查看Pod详情
kubectl describe pod <pod-name> -n agent-manager
# 查看事件
kubectl get events -n agent-manager --sort-by='.lastTimestamp'
# 检查ServiceAccount
kubectl get sa -n agent-manager
kubectl describe sa agent-manager-sa -n agent-manager
# 检查RoleBinding
kubectl get rolebinding -n agent-manager
kubectl describe rolebinding agent-manager-role-binding -n agent-manager
# 进入Pod调试
kubectl exec -it <pod-name> -n agent-manager -- /bin/bash
```
### 日志级别
在Deployment中设置环境变量调整日志级别：
```yaml
env:
- name: LOG_LEVEL
value: "DEBUG" # DEBUG, INFO, WARNING, ERROR
```
## 参考资料
- [Kubernetes官方文档](https://kubernetes.io/docs/)
- [Azure Kubernetes Service文档](https://docs.microsoft.com/azure/aks/)
- [Azure DNS文档](https://docs.microsoft.com/azure/dns/)
- [Agent Manager API文档](../docs/API_DOCUMENTATION.md)
- [DNS问题修复报告](../docs/DNS_ISSUE_FIX_REPORT.md)
## 联系支持
如有问题，请：
1. 查看本文档的常见问题部分
2. 查看`docs/DNS_ISSUE_FIX_REPORT.md`
3. 查看agent-manager日志
4. 联系开发团队
k8s/agent-manager-deployment.yaml
+1 -1
View File
@@ -31,7 +31,7 @@ spec:
containers:
- name: agent-manager
image: agnettaiji.azurecr.io/agent-manager:latest-arm64
image: agnettaiji.azurecr.io/ai-agents/agent-manager:latest
imagePullPolicy: Always
ports: