# 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 ```bash 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` 中添加： ```bash # 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 模式： ```python # 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）： ```python # 改造前 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"] ``` **引用检测**： ```python # 改造前 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： ```python # 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 联合部署 ```yaml # 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 ``` ### 提交任务示例 ```bash # 指定 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 ```python 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 速查 ```bash 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 --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 的默认配置。