12 KiB

Raw Blame History

GEO 系统与 AgentKit 联通指南

一、AgentKit 是什么

AgentKit 是一个统一 Agent 开发框架，核心能力：

能力	说明
ReAct 推理引擎	Think → Act → Observe 循环，LLM 自主选择工具、决定何时输出
LLM Gateway	统一 LLM 调用入口，管理 API Key、模型路由、降级策略、用量统计
Skill 系统	YAML 配置定义技能（Prompt + Tool + 质量门禁），无需写代码
意图路由	关键词匹配（零成本）+ LLM 分类（兜底），自动路由到最佳 Skill
产出质量管理	必填字段、最低字数、Schema 校验、自定义验证器，不通过自动重试
标准化输出	Schema 验证 + 类型归一化 + 元数据附加，所有 Skill 产出格式统一
记忆系统	语义记忆（pgvector）+ 情景记忆（Redis）+ 工作记忆
MCP 协议	支持 Model Context Protocol，可连接外部工具服务器
CLI 工具	`agentkit` 命令行，支持 init/serve/task/skill/pair/doctor/usage
独立部署	FastAPI Server + Docker，业务系统通过 HTTP API 调用

一句话总结：AgentKit 让你从写 150 行 Agent 代码降为 10-20 行 YAML 配置。

二、架构关系

┌──────────────────────┐     HTTP API      ┌──────────────────────────┐
│    GEO Backend       │ ───────────────→  │   AgentKit Server        │
│    (FastAPI :8000)   │                   │   (FastAPI :8001)        │
│                      │  POST /tasks      │                          │
│  不再 import         │  GET /tasks/{id}  │  Intent Router           │
│  agentkit 内部类     │  GET /skills      │  ReAct Engine            │
│                      │  GET /llm/usage   │  LLM Gateway             │
│  只用 AgentKitClient │                   │  Quality Gate            │
│                      │  ←── callback ─── │  Output Standardizer     │
│  /internal/* API     │  (custom_handler) │  AgentPool + SkillRegistry│
└──────────────────────┘                   └──────────────────────────┘
                                                    │
                                              ┌─────┴─────┐
                                              │  LLM APIs  │
                                              │ (DeepSeek  │
                                              │  OpenAI…)  │
                                              └───────────┘

关键原则：

GEO Backend 不 import agentkit 内部类，只通过 HTTP API 调用
AgentKit Server 不直接访问 GEO 数据库，需要 DB 时回调 GEO 的内部 API
LLM API Key 只在 AgentKit Server 中配置，GEO 不需要

三、联通步骤

Step 1：部署 AgentKit Server

cd fischer-agentkit

# 初始化配置
agentkit init

# 编辑 .env，填入 LLM API Key
cp .env.example .env
# DEEPSEEK_API_KEY=sk-xxx
# OPENAI_API_KEY=sk-xxx

# 配对 GEO 业务系统
agentkit pair --name geo-backend --skills-dir ./configs/skills
# 输出: API Key = ak_live_xxxxxxxxxxxx

# 启动 Server
agentkit serve --host 0.0.0.0 --port 8001

# 验证
agentkit doctor

Step 2：GEO Backend 配置环境变量

在 GEO 的 .env 中添加：

# AgentKit Server 连接
AGENTKIT_SERVER_URL=http://localhost:8001
AGENTKIT_API_KEY=ak_live_xxxxxxxxxxxx   # Step 1 中 pair 生成的 key

Step 3：改造 GEO 的 agent_framework 适配层

将 app/agent_framework/adapter.py 从 import 模式改为 HTTP API 模式：

# app/agent_framework/adapter.py — Mode A 版本
import os
import logging
from agentkit.server.client import AgentKitClient

logger = logging.getLogger(__name__)
_CLIENT: AgentKitClient | None = None

def get_agentkit_client() -> AgentKitClient:
    """获取 AgentKit Server HTTP 客户端"""
    global _CLIENT
    if _CLIENT is None:
        base_url = os.getenv("AGENTKIT_SERVER_URL", "http://localhost:8001")
        api_key = os.getenv("AGENTKIT_API_KEY")
        _CLIENT = AgentKitClient(base_url=base_url, api_key=api_key)
    return _CLIENT

async def submit_task(input_data: dict, skill_name: str | None = None) -> dict:
    """提交任务到 AgentKit Server"""
    client = get_agentkit_client()
    return await client.submit_task(input_data=input_data, skill_name=skill_name)

async def get_task_status(task_id: str) -> dict:
    """查询任务状态"""
    client = get_agentkit_client()
    return await client.get_task_status(task_id)

async def get_llm_usage(agent_name: str | None = None) -> dict:
    """查询 LLM 用量"""
    client = get_agentkit_client()
    return await client.get_usage(agent_name=agent_name)

Step 4：改造业务调用

内容生成（原来 3 次 dispatch → 1 次 submit_task）：

# 改造前
from app.agent_framework.dispatcher import TaskDispatcher
dispatcher = TaskDispatcher(settings.REDIS_URL)
task = TaskMessage(agent_name="content_generator", ...)
result = await dispatcher.dispatch(task, ...)

# 改造后
from app.agent_framework.adapter import submit_task
result = await submit_task(
    input_data={"target_keyword": keyword, "brand_name": brand, ...},
    skill_name="content_generator",
)
content = result["data"]["content"]

引用检测：

# 改造前
from app.agent_framework.agents import CitationDetectorAgent
agent = CitationDetectorAgent()
result = await agent.execute(task)

# 改造后
from app.agent_framework.adapter import submit_task
result = await submit_task(
    input_data={"keyword": keyword, "platform": platform, ...},
    skill_name="citation_detector",
)

Step 5：新增内部 API（供 AgentKit Server 回调）

custom_handler 需要 DB 访问时，AgentKit Server 通过 HTTP 回调 GEO：

# app/api/internal.py
from fastapi import APIRouter, Depends
from sqlalchemy.ext.asyncio import AsyncSession
from app.database import get_db

router = APIRouter(prefix="/internal", tags=["internal"])

@router.post("/citation/detect")
async def citation_detect(input_data: dict, db: AsyncSession = Depends(get_db)):
    """供 AgentKit Server 的 citation_handler 回调"""
    from app.services.citation.citation import CitationService
    service = CitationService()
    return await service.detect_full(input_data, db=db)

@router.post("/knowledge/search")
async def knowledge_search(input_data: dict, db: AsyncSession = Depends(get_db)):
    """供 AgentKit Server 的 retrieve_knowledge Tool 回调"""
    from app.services.knowledge.rag_service import RAGService
    service = RAGService()
    results = await service.search(session=db, query=input_data["query"])
    return {"results": results}

Step 6：Docker Compose 联合部署

# docker-compose.yml
version: "3.8"
services:
  geo-backend:
    build: ./geo/backend
    ports: ["8000:8000"]
    environment:
      - AGENTKIT_SERVER_URL=http://agentkit-server:8001
      - AGENTKIT_API_KEY=${AGENTKIT_API_KEY}
    depends_on:
      - agentkit-server

  agentkit-server:
    build: ./fischer-agentkit
    command: serve --host 0.0.0.0 --port 8001
    ports: ["8001:8001"]
    env_file: ./fischer-agentkit/.env
    environment:
      - GEO_BACKEND_URL=http://geo-backend:8000
    depends_on:
      - redis
      - postgres

  redis:
    image: redis:7-alpine

  postgres:
    image: pgvector/pgvector:pg15
    environment:
      POSTGRES_USER: agentkit
      POSTGRES_PASSWORD: agentkit
      POSTGRES_DB: agentkit

四、GEO 当前 8 个 Skill 映射

原 Agent 名	Skill 名	模式	改造要点
citation_detector	citation_detector	custom	handler 回调 GEO `/internal/citation/detect`
monitor	monitor	custom	handler 回调 GEO `/internal/monitor/check`
schema_advisor	schema_advisor	custom	handler 回调 GEO `/internal/schema/advise`
content_generator	content_generator	llm_generate	直接迁移 YAML，添加 intent + quality_gate
deai_agent	deai_agent	llm_generate	直接迁移 YAML
geo_optimizer	geo_optimizer	llm_generate	直接迁移 YAML
competitor_analyzer	competitor_analyzer	tool_call	Tool 迁移到 AgentKit Server
trend_agent	trend_agent	tool_call	Tool 迁移到 AgentKit Server

YAML 零修改：现有 8 个 YAML 配置无需修改即可被 AgentKit 加载（SkillConfig 向后兼容 AgentConfig）。建议为 llm_generate 模式的 Skill 添加 intent 和 quality_gate 字段以启用新能力。

五、API 参考

AgentKit Server REST API

路径	方法	说明
`POST /api/v1/tasks`	POST	提交任务（支持意图路由自动匹配 Skill）
`GET /api/v1/tasks/{id}`	GET	查询任务状态和结果
`GET /api/v1/tasks`	GET	列出任务
`DELETE /api/v1/tasks/{id}`	DELETE	取消任务
`POST /api/v1/agents`	POST	创建 Agent 实例
`GET /api/v1/agents`	GET	列出 Agent 实例
`POST /api/v1/skills`	POST	注册 Skill
`GET /api/v1/skills`	GET	列出已注册 Skill
`GET /api/v1/llm/usage`	GET	查询 LLM 用量统计
`GET /api/v1/health`	GET	健康检查

认证

所有 API 请求需携带 Header：

X-API-Key: ak_live_xxxxxxxxxxxx

提交任务示例

# 指定 Skill
curl -X POST http://localhost:8001/api/v1/tasks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ak_live_xxxxxxxxxxxx" \
  -d '{
    "skill_name": "content_generator",
    "input_data": {"target_keyword": "AI", "brand_name": "BrandX"}
  }'

# 意图路由自动匹配
curl -X POST http://localhost:8001/api/v1/tasks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ak_live_xxxxxxxxxxxx" \
  -d '{
    "input_data": {"query": "帮我生成一篇关于AI的文章"}
  }'

Python SDK

from agentkit.server.client import AgentKitClient

client = AgentKitClient(
    base_url="http://localhost:8001",
    api_key="ak_live_xxxxxxxxxxxx",
)

# 提交任务
result = await client.submit_task(
    skill_name="content_generator",
    input_data={"target_keyword": "AI", "brand_name": "BrandX"},
)

# 查询用量
usage = await client.get_usage()

六、CLI 速查

agentkit init                    # 初始化项目配置
agentkit serve --port 8001       # 启动 Server
agentkit doctor                  # 诊断健康状态
agentkit version                 # 查看版本

agentkit pair --name geo-backend # 配对业务系统，生成 API Key
agentkit pair --list             # 查看已配对客户端
agentkit pair --revoke geo-backend  # 撤销配对

agentkit task submit --skill content_generator --input '{"topic":"AI"}' --server-url http://localhost:8001
agentkit task status <task_id> --server-url http://localhost:8001
agentkit task list --server-url http://localhost:8001

agentkit skill list --server-url http://localhost:8001
agentkit skill load ./my_skill.yaml
agentkit skill info content_generator --server-url http://localhost:8001

agentkit usage --server-url http://localhost:8001

七、迁移检查清单

Phase 1：AgentKit Server 部署

agentkit init 生成配置
.env 填入 LLM API Key
agentkit pair --name geo-backend 生成 API Key
8 个 YAML 配置复制到 configs/skills/
14 个 FunctionTool 迁移到 configs/geo_tools.py
3 个 custom_handler 迁移到 configs/geo_handlers.py
agentkit serve 启动成功
agentkit doctor 健康检查通过

Phase 2：GEO Backend 改造

.env 添加 AGENTKIT_SERVER_URL + AGENTKIT_API_KEY
adapter.py 改为 HTTP API 模式
content_generation_service.py 改用 submit_task()
citation.py 改用 submit_task()
scheduler.py 改用 submit_task()
新增 /internal/* API 路由
端到端测试通过

Phase 3：清理

删除旧框架文件（base.py, dispatcher.py, registry.py 等）
删除旧 Agent 类
更新 __init__.py 导出
全量回归测试

八、配置优先级

客户端自定义配置（pair 时 --skills-dir 指定）
        ↓ 覆盖
init 默认配置（agentkit.yaml）
        ↓ 覆盖
硬编码默认值

业务系统可以通过 agentkit pair --name geo-backend --skills-dir ./custom_skills 指定自己的 Skill 目录，优先级高于 AgentKit Server 的默认配置。

12 KiB Raw Blame History Unescape Escape