1123 lines
44 KiB
Python
1123 lines
44 KiB
Python
"""ConfigDrivenAgent - 配置驱动的 Agent 定义
|
||
|
||
核心设计：
|
||
- 从 YAML/Dict 配置自动组装 Agent（Prompt + LLM + Tool + Memory）
|
||
- 支持三种任务模式：llm_generate / tool_call / custom
|
||
- v2: 支持 SkillConfig + ReAct 执行模式 + LLMGateway + Quality Gate
|
||
- 新增 Agent 从写 150 行代码降为 10-20 行配置
|
||
"""
|
||
|
||
import json
|
||
import logging
|
||
import os
|
||
from typing import Callable, Coroutine
|
||
|
||
import yaml
|
||
|
||
from agentkit.core.base import BaseAgent
|
||
from agentkit.core.exceptions import ConfigValidationError
|
||
from agentkit.core.protocol import AgentCapability, TaskMessage
|
||
from agentkit.evolution.lifecycle import EvolutionMixin
|
||
from agentkit.evolution.reflector import Reflector
|
||
from agentkit.prompts.section import PromptSection
|
||
from agentkit.prompts.template import PromptTemplate
|
||
from agentkit.tools.base import Tool
|
||
from agentkit.tools.registry import ToolRegistry
|
||
|
||
logger = logging.getLogger(__name__)
|
||
|
||
|
||
class AgentConfig:
|
||
"""Agent 配置模型，从 YAML 或 Dict 构建"""
|
||
|
||
def __init__(
|
||
self,
|
||
name: str,
|
||
agent_type: str,
|
||
version: str = "1.0.0",
|
||
description: str = "",
|
||
task_mode: str = "llm_generate",
|
||
supported_tasks: list[str] | None = None,
|
||
max_concurrency: int = 1,
|
||
input_schema: dict[str, object] | None = None,
|
||
output_schema: dict[str, object] | None = None,
|
||
prompt: dict[str, str] | None = None,
|
||
llm: dict[str, object] | None = None,
|
||
tools: list[str] | None = None,
|
||
memory: dict[str, object] | None = None,
|
||
custom_handler: str | None = None,
|
||
):
|
||
self.name = name
|
||
self.agent_type = agent_type
|
||
self.version = version
|
||
self.description = description
|
||
self.task_mode = task_mode
|
||
self.supported_tasks = supported_tasks or [agent_type]
|
||
self.max_concurrency = max_concurrency
|
||
self.input_schema = input_schema
|
||
self.output_schema = output_schema
|
||
self.prompt = prompt or {}
|
||
self.llm = llm or {}
|
||
self.tools = tools or []
|
||
self.memory = memory or {}
|
||
self.custom_handler = custom_handler
|
||
|
||
self._validate()
|
||
|
||
def _validate(self) -> None:
|
||
"""校验配置合法性"""
|
||
valid_modes = {"llm_generate", "tool_call", "custom"}
|
||
if self.task_mode not in valid_modes:
|
||
raise ConfigValidationError(
|
||
agent_name=self.name,
|
||
key="task_mode",
|
||
reason=f"Invalid task_mode '{self.task_mode}', must be one of {valid_modes}",
|
||
)
|
||
|
||
if self.task_mode == "llm_generate" and not self.prompt:
|
||
raise ConfigValidationError(
|
||
agent_name=self.name,
|
||
key="prompt",
|
||
reason="llm_generate mode requires 'prompt' configuration",
|
||
)
|
||
|
||
if self.task_mode == "tool_call" and not self.tools:
|
||
raise ConfigValidationError(
|
||
agent_name=self.name,
|
||
key="tools",
|
||
reason="tool_call mode requires at least one tool in 'tools' list",
|
||
)
|
||
|
||
if self.task_mode == "custom" and not self.custom_handler:
|
||
raise ConfigValidationError(
|
||
agent_name=self.name,
|
||
key="custom_handler",
|
||
reason="custom mode requires 'custom_handler' (dotted path to callable)",
|
||
)
|
||
|
||
@classmethod
|
||
def from_dict(cls, data: dict[str, object]) -> "AgentConfig":
|
||
"""从字典创建配置"""
|
||
return cls(
|
||
name=data["name"],
|
||
agent_type=data["agent_type"],
|
||
version=data.get("version", "1.0.0"),
|
||
description=data.get("description", ""),
|
||
task_mode=data.get("task_mode", "llm_generate"),
|
||
supported_tasks=data.get("supported_tasks"),
|
||
max_concurrency=data.get("max_concurrency", 1),
|
||
input_schema=data.get("input_schema"),
|
||
output_schema=data.get("output_schema"),
|
||
prompt=data.get("prompt"),
|
||
llm=data.get("llm"),
|
||
tools=data.get("tools"),
|
||
memory=data.get("memory"),
|
||
custom_handler=data.get("custom_handler"),
|
||
)
|
||
|
||
@classmethod
|
||
def from_yaml(cls, path: str) -> "AgentConfig":
|
||
"""从 YAML 文件加载配置"""
|
||
with open(path, "r", encoding="utf-8") as f:
|
||
data = yaml.safe_load(f)
|
||
if not isinstance(data, dict):
|
||
raise ConfigValidationError(
|
||
agent_name="unknown",
|
||
key="config",
|
||
reason=f"YAML config must be a mapping, got {type(data)}",
|
||
)
|
||
return cls.from_dict(data)
|
||
|
||
def to_dict(self) -> dict[str, object]:
|
||
"""序列化为字典"""
|
||
d = {
|
||
"name": self.name,
|
||
"agent_type": self.agent_type,
|
||
"version": self.version,
|
||
"description": self.description,
|
||
"task_mode": self.task_mode,
|
||
"supported_tasks": self.supported_tasks,
|
||
"max_concurrency": self.max_concurrency,
|
||
}
|
||
if self.input_schema:
|
||
d["input_schema"] = self.input_schema
|
||
if self.output_schema:
|
||
d["output_schema"] = self.output_schema
|
||
if self.prompt:
|
||
d["prompt"] = self.prompt
|
||
if self.llm:
|
||
d["llm"] = self.llm
|
||
if self.tools:
|
||
d["tools"] = self.tools
|
||
if self.memory:
|
||
d["memory"] = self.memory
|
||
if self.custom_handler:
|
||
d["custom_handler"] = self.custom_handler
|
||
return d
|
||
|
||
|
||
class ConfigDrivenAgent(BaseAgent, EvolutionMixin):
|
||
"""配置驱动的 Agent
|
||
|
||
从 YAML/Dict 配置自动组装，支持三种任务模式：
|
||
- llm_generate: 渲染 Prompt → 调用 LLM → 解析 JSON 输出
|
||
- tool_call: 调用注册的 Tool 并返回结果
|
||
- custom: 自定义 handler 函数
|
||
|
||
v2 增强：
|
||
- 接受 SkillConfig，自动创建 Skill 并启用 ReAct 模式
|
||
- llm_gateway 参数直接传入 LLMGateway
|
||
- llm_client 参数自动包装为 LLMGateway（向后兼容）
|
||
- Quality Gate 自动集成
|
||
|
||
示例 YAML 配置::
|
||
|
||
name: content_generator
|
||
agent_type: content_generation
|
||
task_mode: llm_generate
|
||
description: "内容生成 Agent"
|
||
prompt:
|
||
identity: "你是一个专业的内容生成助手"
|
||
instructions: "根据用户需求生成高质量内容"
|
||
output_format: "以 JSON 格式输出"
|
||
llm:
|
||
model: "gpt-4"
|
||
temperature: 0.7
|
||
tools:
|
||
- retrieve_knowledge
|
||
"""
|
||
|
||
# Security: whitelist of allowed module prefixes for dynamic handler import
|
||
_ALLOWED_HANDLER_PREFIXES = (
|
||
"agentkit.",
|
||
"app.agent_framework.",
|
||
)
|
||
|
||
def __init__(
|
||
self,
|
||
config: AgentConfig,
|
||
tool_registry: ToolRegistry | None = None,
|
||
llm_client: object | None = None,
|
||
custom_handlers: dict[str, Callable[..., Coroutine]] | None = None,
|
||
llm_gateway: object | None = None, # NEW v2 param: LLMGateway
|
||
mcp_servers: dict[str, str] | None = None, # NEW v2 param: MCP server URLs
|
||
compressor: object | None = None, # CompressionStrategy | None
|
||
):
|
||
# v2: If SkillConfig, extract skill info
|
||
from agentkit.skills.base import SkillConfig, Skill
|
||
|
||
self._skill_config: SkillConfig | None = None
|
||
self._skill_instance: Skill | None = None
|
||
|
||
if isinstance(config, SkillConfig):
|
||
self._skill_config = config
|
||
self._skill_instance = Skill(config=config)
|
||
|
||
self._config = config
|
||
self._tool_registry = tool_registry or ToolRegistry()
|
||
self._llm_client = llm_client
|
||
self._custom_handlers = custom_handlers or {}
|
||
self._prompt_template: PromptTemplate | None = None
|
||
|
||
# Call super().__init__() first
|
||
super().__init__(
|
||
name=config.name,
|
||
agent_type=config.agent_type,
|
||
version=config.version,
|
||
)
|
||
|
||
# v2: Backward compat — wrap llm_client into LLMGateway if no gateway provided
|
||
if llm_gateway is not None:
|
||
self._llm_gateway = llm_gateway
|
||
elif llm_client is not None:
|
||
self._llm_gateway = self._wrap_llm_client(llm_client)
|
||
else:
|
||
self._llm_gateway = None
|
||
|
||
# v2: Set skill on base agent
|
||
if self._skill_instance:
|
||
self._skill = self._skill_instance
|
||
|
||
# v2: Initialize ReAct engine if gateway available
|
||
self._react_engine = None
|
||
if self._llm_gateway:
|
||
from agentkit.core.react import ReActEngine
|
||
|
||
self._react_engine = ReActEngine(
|
||
llm_gateway=self._llm_gateway,
|
||
max_steps=getattr(config, "max_steps", 5),
|
||
)
|
||
|
||
# v2: Initialize Quality Gate (always available)
|
||
from agentkit.quality.gate import QualityGate
|
||
|
||
self._quality_gate = QualityGate()
|
||
|
||
# v2: Initialize Evolution if configured
|
||
evolution_config = getattr(config, "evolution", None)
|
||
if evolution_config is not None:
|
||
# Support both dict and EvolutionConfig
|
||
if isinstance(evolution_config, dict):
|
||
is_enabled = evolution_config.get("enabled", False)
|
||
else:
|
||
is_enabled = getattr(evolution_config, "enabled", False)
|
||
else:
|
||
is_enabled = False
|
||
|
||
if is_enabled:
|
||
reflector = Reflector()
|
||
EvolutionMixin.__init__(
|
||
self,
|
||
reflector=reflector,
|
||
)
|
||
self._evolution_enabled = True
|
||
else:
|
||
EvolutionMixin.__init__(self) # Initialize with no components
|
||
self._evolution_enabled = False
|
||
|
||
# v2: Initialize Output Standardizer
|
||
from agentkit.quality.output import OutputStandardizer
|
||
|
||
self._output_standardizer = OutputStandardizer()
|
||
|
||
# v2: Store compressor for ReAct engine
|
||
self._compressor = compressor
|
||
|
||
# 从配置构建 Prompt 模板
|
||
if config.prompt:
|
||
sections = PromptSection(
|
||
identity=config.prompt.get("identity", ""),
|
||
context=config.prompt.get("context", ""),
|
||
instructions=config.prompt.get("instructions", ""),
|
||
constraints=config.prompt.get("constraints", ""),
|
||
output_format=config.prompt.get("output_format", ""),
|
||
examples=config.prompt.get("examples", ""),
|
||
)
|
||
self._prompt_template = PromptTemplate(
|
||
sections=sections,
|
||
name=config.name,
|
||
version=config.version,
|
||
)
|
||
|
||
# 从配置绑定 Tool
|
||
self._bind_tools()
|
||
|
||
# v2: Merge Skill-bound tools into Agent's tool list
|
||
if self._skill_instance and self._skill_instance.tools:
|
||
for tool in self._skill_instance.tools:
|
||
if not any(t.name == tool.name for t in self._tools):
|
||
self.use_tool(tool)
|
||
logger.info(f"Merged skill tool '{tool.name}' into agent '{self.name}'")
|
||
|
||
# v2: Register MCP tools if mcp_servers provided
|
||
self._mcp_clients: list[object] = []
|
||
self._mcp_servers: dict[str, str] = mcp_servers or {}
|
||
self._mcp_tools_registered = False
|
||
|
||
# Memory integration: 从 config.memory 自动实例化 MemoryRetriever
|
||
self._memory_retriever: object | None = None
|
||
if config.memory:
|
||
try:
|
||
from agentkit.memory.retriever import MemoryRetriever
|
||
from agentkit.memory.working import WorkingMemory
|
||
from agentkit.memory.semantic import SemanticMemory
|
||
from agentkit.memory.http_rag import HttpRAGService
|
||
|
||
working = None
|
||
episodic = None
|
||
semantic = None
|
||
|
||
if config.memory.get("working", {}).get("enabled"):
|
||
import redis.asyncio as aioredis
|
||
|
||
redis_url = config.memory["working"].get("redis_url", "redis://localhost:6379")
|
||
redis_client = aioredis.from_url(redis_url, decode_responses=True)
|
||
working = WorkingMemory(redis=redis_client)
|
||
|
||
if config.memory.get("episodic", {}).get("enabled"):
|
||
from agentkit.memory.episodic import EpisodicMemory
|
||
from agentkit.memory.embedder import OpenAIEmbedder, EmbeddingCache
|
||
|
||
epi_conf = config.memory["episodic"]
|
||
embedder = None
|
||
if epi_conf.get("embedder_api_key") or os.environ.get("OPENAI_API_KEY"):
|
||
cache = EmbeddingCache(
|
||
max_size=epi_conf.get("cache_max_size", 1000),
|
||
ttl=epi_conf.get("cache_ttl", 3600),
|
||
)
|
||
embedder = OpenAIEmbedder(
|
||
api_key=epi_conf.get("embedder_api_key"),
|
||
model=epi_conf.get("embedder_model", "text-embedding-3-small"),
|
||
base_url=epi_conf.get("embedder_base_url"),
|
||
cache=cache,
|
||
)
|
||
episodic = EpisodicMemory(
|
||
session_factory=None, # Set externally when DB session is available
|
||
episodic_model=None, # Set externally when ORM model is available
|
||
embedder=embedder,
|
||
decay_rate=epi_conf.get("decay_rate", 0.01),
|
||
alpha=epi_conf.get("alpha", 0.7),
|
||
retrieve_limit=epi_conf.get("retrieve_limit", 200),
|
||
pgvector_enabled=epi_conf.get("pgvector_enabled", True),
|
||
table_name=epi_conf.get("table_name", "episodic_memories"),
|
||
)
|
||
|
||
if config.memory.get("semantic", {}).get("enabled"):
|
||
sem_conf = config.memory["semantic"]
|
||
rag_service = HttpRAGService(
|
||
base_url=sem_conf["base_url"],
|
||
api_key=sem_conf.get("api_key"),
|
||
knowledge_base_ids=sem_conf.get("knowledge_base_ids", []),
|
||
timeout=sem_conf.get("timeout", 30),
|
||
)
|
||
semantic = SemanticMemory(
|
||
rag_service=rag_service,
|
||
knowledge_base_ids=sem_conf.get("knowledge_base_ids", []),
|
||
search_mode=sem_conf.get("search_mode", "standard"),
|
||
use_rerank=sem_conf.get("use_rerank", True),
|
||
use_compression=sem_conf.get("use_compression", False),
|
||
kb_weights=sem_conf.get("kb_weights"),
|
||
)
|
||
|
||
self._memory_retriever = MemoryRetriever(
|
||
working_memory=working,
|
||
episodic_memory=episodic,
|
||
semantic_memory=semantic,
|
||
)
|
||
|
||
# Inject into BaseAgent
|
||
self._memory_retriever_ref = self._memory_retriever
|
||
|
||
logger.info(f"ConfigDrivenAgent '{self.name}' initialized memory system")
|
||
except Exception as e:
|
||
logger.warning(f"Failed to initialize memory system: {e}")
|
||
self._memory_retriever = None
|
||
|
||
# Auto-register retrieve_knowledge tool if semantic memory is configured
|
||
if self._memory_retriever:
|
||
retrieve_tool = self._memory_retriever.create_retrieve_tool()
|
||
if retrieve_tool:
|
||
self.use_tool(retrieve_tool)
|
||
|
||
def get_tools(self) -> list[Tool]:
|
||
"""Return registered tools for this agent (from config + post-init registration)."""
|
||
all_tools = list(self._tools)
|
||
if self._tool_registry:
|
||
for tool in self._tool_registry.list_tools():
|
||
if not any(t.name == tool.name for t in all_tools):
|
||
all_tools.append(tool)
|
||
return all_tools
|
||
|
||
def get_model(self) -> str:
|
||
"""Return the LLM model name for this agent."""
|
||
return self._config.llm.get("model", "default") if self._config.llm else "default"
|
||
|
||
def get_system_prompt(self) -> str | None:
|
||
"""Return the system prompt for this agent, including available tools."""
|
||
parts = []
|
||
|
||
if self._prompt_template:
|
||
sections = self._prompt_template._sections
|
||
for key in ("identity", "context", "instructions", "constraints", "output_format"):
|
||
val = getattr(sections, key, "")
|
||
if val:
|
||
parts.append(val)
|
||
|
||
# Append available tools description so the LLM knows what it can use
|
||
# Use _tool_registry (which may have tools registered post-init) as well as _tools (from config)
|
||
all_tools = list(self._tools)
|
||
if self._tool_registry:
|
||
for tool in self._tool_registry.list_tools():
|
||
if not any(t.name == tool.name for t in all_tools):
|
||
all_tools.append(tool)
|
||
if all_tools:
|
||
tools_desc = self._build_tools_description(all_tools)
|
||
parts.append(f"\n\n## 可用工具\n{tools_desc}")
|
||
|
||
return "\n".join(parts) if parts else None
|
||
|
||
def _build_tools_description(self, tools: list | None = None) -> str:
|
||
"""Build a text description of available tools for the system prompt."""
|
||
tools = tools or self._tools
|
||
lines = []
|
||
for tool in tools:
|
||
lines.append(f"- **{tool.name}**: {tool.description}")
|
||
if tool.input_schema and "properties" in tool.input_schema:
|
||
params = list(tool.input_schema["properties"].keys())
|
||
if params:
|
||
lines[-1] += f" (参数: {', '.join(params)})"
|
||
return "\n".join(lines)
|
||
|
||
def get_react_config(self) -> dict:
|
||
"""Return ReAct engine configuration."""
|
||
max_steps = 10
|
||
timeout_seconds = None
|
||
if self._skill_config:
|
||
max_steps = self._skill_config.max_steps
|
||
timeout_seconds = getattr(self._skill_config, "timeout_seconds", None)
|
||
return {
|
||
"max_steps": max_steps,
|
||
"timeout_seconds": timeout_seconds,
|
||
}
|
||
|
||
@property
|
||
def config(self) -> AgentConfig:
|
||
return self._config
|
||
|
||
@property
|
||
def prompt_template(self) -> PromptTemplate | None:
|
||
return self._prompt_template
|
||
|
||
async def on_task_complete(self, task: TaskMessage, output: dict) -> None:
|
||
"""Task complete hook - trigger evolution if enabled"""
|
||
if self._evolution_enabled:
|
||
try:
|
||
from agentkit.core.protocol import TaskResult, TaskStatus
|
||
from datetime import datetime, timezone
|
||
|
||
result = TaskResult(
|
||
task_id=task.task_id,
|
||
agent_name=self.name,
|
||
status=TaskStatus.COMPLETED,
|
||
output_data=output,
|
||
error_message=None,
|
||
started_at=datetime.now(timezone.utc),
|
||
completed_at=datetime.now(timezone.utc),
|
||
)
|
||
await self.evolve_after_task(task, result)
|
||
except Exception as e:
|
||
logger.warning(f"Evolution after task failed: {e}")
|
||
|
||
async def on_task_failed(self, task: TaskMessage, error: Exception) -> None:
|
||
"""Task failed hook - record failure for evolution"""
|
||
if self._evolution_enabled:
|
||
try:
|
||
from agentkit.core.protocol import TaskResult, TaskStatus
|
||
from datetime import datetime, timezone
|
||
|
||
result = TaskResult(
|
||
task_id=task.task_id,
|
||
agent_name=self.name,
|
||
status=TaskStatus.FAILED,
|
||
output_data=None,
|
||
error_message=str(error),
|
||
started_at=datetime.now(timezone.utc),
|
||
completed_at=datetime.now(timezone.utc),
|
||
)
|
||
await self.evolve_after_task(task, result)
|
||
except Exception as e:
|
||
logger.warning(f"Evolution after task failure failed: {e}")
|
||
|
||
def _bind_tools(self) -> None:
|
||
"""根据配置绑定工具"""
|
||
for tool_name in self._config.tools:
|
||
try:
|
||
tool = self._tool_registry.get(tool_name)
|
||
self.use_tool(tool)
|
||
logger.info(f"ConfigDrivenAgent '{self.name}' bound tool '{tool_name}'")
|
||
except Exception as e:
|
||
logger.warning(
|
||
f"ConfigDrivenAgent '{self.name}' failed to bind tool '{tool_name}': {e}"
|
||
)
|
||
|
||
def _auto_set_current_module(self) -> None:
|
||
"""Auto-set _current_module from SkillConfig for evolution.
|
||
|
||
Creates a Module from the current SkillConfig's instruction/prompt
|
||
so that prompt optimization has a target to work with.
|
||
"""
|
||
from agentkit.evolution.prompt_optimizer import Module, Signature
|
||
|
||
prompt = self._config.prompt or {}
|
||
instruction_parts = []
|
||
for key in ("identity", "instructions", "constraints"):
|
||
val = prompt.get(key, "")
|
||
if val:
|
||
instruction_parts.append(val)
|
||
instruction = "\n".join(instruction_parts)
|
||
|
||
input_fields = {}
|
||
if self._config.input_schema:
|
||
for field_name, field_info in self._config.input_schema.items():
|
||
input_fields[field_name] = (
|
||
str(field_info) if not isinstance(field_info, str) else field_info
|
||
)
|
||
|
||
output_fields = {}
|
||
if self._config.output_schema:
|
||
for field_name, field_info in self._config.output_schema.items():
|
||
output_fields[field_name] = (
|
||
str(field_info) if not isinstance(field_info, str) else field_info
|
||
)
|
||
|
||
module = Module(
|
||
name=self.name,
|
||
signature=Signature(
|
||
input_fields=input_fields or {"input": "task input"},
|
||
output_fields=output_fields or {"output": "task output"},
|
||
instruction=instruction,
|
||
),
|
||
)
|
||
self.set_current_module(module)
|
||
logger.debug(f"Auto-set _current_module for agent '{self.name}'")
|
||
|
||
async def _register_mcp_tools(self) -> None:
|
||
"""Lazily register tools from MCP servers as agent tools.
|
||
|
||
Called on first task execution to allow async MCP client operations.
|
||
"""
|
||
if self._mcp_tools_registered or not self._mcp_servers:
|
||
return
|
||
|
||
self._mcp_tools_registered = True
|
||
from agentkit.mcp.client import MCPClient
|
||
|
||
for server_name, base_url in self._mcp_servers.items():
|
||
try:
|
||
client = MCPClient(server_url=base_url)
|
||
self._mcp_clients.append(client)
|
||
|
||
# List available tools from the MCP server
|
||
tools = await client.list_tools()
|
||
for tool_info in tools:
|
||
tool_name = tool_info.get("name", "")
|
||
tool_desc = tool_info.get("description", "")
|
||
if not tool_name:
|
||
continue
|
||
|
||
# Create MCPTool and register it
|
||
mcp_tool = client.as_tool(tool_name, tool_desc)
|
||
self.use_tool(mcp_tool)
|
||
logger.info(
|
||
f"Agent '{self.name}' registered MCP tool '{tool_name}' "
|
||
f"from server '{server_name}'"
|
||
)
|
||
except Exception as e:
|
||
logger.warning(
|
||
f"Agent '{self.name}' failed to connect to MCP server "
|
||
f"'{server_name}' at {base_url}: {e}"
|
||
)
|
||
|
||
def get_capabilities(self) -> AgentCapability:
|
||
return AgentCapability(
|
||
agent_name=self.name,
|
||
agent_type=self.agent_type,
|
||
version=self.version,
|
||
supported_tasks=self._config.supported_tasks,
|
||
max_concurrency=self._config.max_concurrency,
|
||
description=self._config.description,
|
||
input_schema=self._config.input_schema,
|
||
output_schema=self._config.output_schema,
|
||
)
|
||
|
||
async def handle_task(self, task: TaskMessage) -> dict:
|
||
"""根据 execution_mode 和 task_mode 执行任务
|
||
|
||
v2 execution_mode 优先级:
|
||
- react: 使用 ReAct 引擎自主推理
|
||
- direct: 直接调用 LLM（不经过 ReAct 循环）
|
||
- custom: 使用自定义 handler
|
||
|
||
如果没有 SkillConfig，回退到传统 task_mode 分支。
|
||
"""
|
||
# Lazy-register MCP tools on first task execution
|
||
await self._register_mcp_tools()
|
||
|
||
# v2: execution_mode routing (when SkillConfig is present)
|
||
if self._skill_config:
|
||
execution_mode = self._skill_config.execution_mode
|
||
|
||
if execution_mode == "react" and self._react_engine:
|
||
return await self._handle_react(task)
|
||
elif execution_mode == "rewoo" and self._react_engine:
|
||
return await self._handle_rewoo(task)
|
||
elif execution_mode == "plan_exec" and self._react_engine:
|
||
return await self._handle_plan_exec(task)
|
||
elif execution_mode == "reflexion" and self._react_engine:
|
||
return await self._handle_reflexion(task)
|
||
elif execution_mode == "direct":
|
||
return await self._handle_direct(task)
|
||
elif execution_mode == "custom":
|
||
return await self._handle_custom(task)
|
||
|
||
# Fall back to existing task_mode modes
|
||
if self._config.task_mode == "llm_generate":
|
||
return await self._handle_llm_generate(task)
|
||
elif self._config.task_mode == "tool_call":
|
||
return await self._handle_tool_call(task)
|
||
elif self._config.task_mode == "custom":
|
||
return await self._handle_custom(task)
|
||
else:
|
||
raise ConfigValidationError(
|
||
agent_name=self.name,
|
||
key="task_mode",
|
||
reason=f"Unknown task_mode: {self._config.task_mode}",
|
||
)
|
||
|
||
async def _handle_react(self, task: TaskMessage) -> dict:
|
||
"""ReAct mode: use ReAct engine for autonomous reasoning"""
|
||
# Auto-set _current_module from SkillConfig if evolution is enabled
|
||
if self._evolution_enabled and self._current_module is None:
|
||
self._auto_set_current_module()
|
||
|
||
# Build variables for prompt rendering
|
||
variables = task.input_data.copy()
|
||
variables["task_type"] = task.task_type
|
||
|
||
# Use PromptTemplate.render() to get full messages (system + user)
|
||
if self._prompt_template:
|
||
rendered_messages = self._prompt_template.render(variables=variables)
|
||
else:
|
||
rendered_messages = [{"role": "user", "content": str(task.input_data)}]
|
||
|
||
# Separate system_prompt from user messages
|
||
# PromptTemplate.render() returns [system_msg, user_msg] or [user_msg]
|
||
system_prompt = None
|
||
user_messages = []
|
||
for msg in rendered_messages:
|
||
if msg["role"] == "system":
|
||
system_prompt = msg["content"]
|
||
else:
|
||
user_messages.append(msg)
|
||
|
||
# If no user messages, add a default one
|
||
if not user_messages:
|
||
user_messages.append({"role": "user", "content": str(task.input_data)})
|
||
|
||
# Get CancellationToken for this task (set by BaseAgent.execute)
|
||
cancellation_token = self._active_tokens.get(task.task_id)
|
||
|
||
# Determine timeout from task or config
|
||
timeout_seconds = float(task.timeout_seconds) if task.timeout_seconds > 0 else None
|
||
|
||
# Execute ReAct loop
|
||
retrieval_config = self._config.memory.get("retrieval", {}) if self._config.memory else {}
|
||
result = await self._react_engine.execute(
|
||
messages=user_messages,
|
||
tools=self.get_tools() or None,
|
||
model=self._config.llm.get("model", "default") if self._config.llm else "default",
|
||
agent_name=self.name,
|
||
task_type=task.task_type,
|
||
system_prompt=system_prompt,
|
||
memory_retriever=self._memory_retriever,
|
||
task_id=task.task_id,
|
||
retrieval_config=retrieval_config or None,
|
||
cancellation_token=cancellation_token,
|
||
timeout_seconds=timeout_seconds,
|
||
compressor=self._compressor,
|
||
)
|
||
|
||
# Parse result
|
||
return self._parse_llm_response(result.output)
|
||
|
||
async def _handle_rewoo(self, task: TaskMessage) -> dict:
|
||
"""ReWOO mode: plan all tool calls upfront, then execute in batch"""
|
||
from agentkit.core.rewoo import ReWOOEngine
|
||
|
||
variables = task.input_data.copy()
|
||
variables["task_type"] = task.task_type
|
||
|
||
if self._prompt_template:
|
||
rendered_messages = self._prompt_template.render(variables=variables)
|
||
else:
|
||
rendered_messages = [{"role": "user", "content": str(task.input_data)}]
|
||
|
||
system_prompt = None
|
||
user_messages = []
|
||
for msg in rendered_messages:
|
||
if msg["role"] == "system":
|
||
system_prompt = msg["content"]
|
||
else:
|
||
user_messages.append(msg)
|
||
|
||
if not user_messages:
|
||
user_messages.append({"role": "user", "content": str(task.input_data)})
|
||
|
||
cancellation_token = self._active_tokens.get(task.task_id)
|
||
timeout_seconds = float(task.timeout_seconds) if task.timeout_seconds > 0 else None
|
||
|
||
rewoo_engine = ReWOOEngine(
|
||
llm_gateway=self._llm_gateway,
|
||
max_plan_steps=self._skill_config.max_steps if self._skill_config else 5,
|
||
default_timeout=300.0,
|
||
fallback_strategies=(
|
||
self._skill_config.fallback_strategies
|
||
if self._skill_config and self._skill_config.fallback_strategies
|
||
else None
|
||
),
|
||
)
|
||
|
||
result = await rewoo_engine.execute(
|
||
messages=user_messages,
|
||
tools=self.get_tools() or None,
|
||
model=self._config.llm.get("model", "default") if self._config.llm else "default",
|
||
agent_name=self.name,
|
||
task_type=task.task_type,
|
||
system_prompt=system_prompt,
|
||
task_id=task.task_id,
|
||
cancellation_token=cancellation_token,
|
||
timeout_seconds=timeout_seconds,
|
||
)
|
||
|
||
return self._parse_llm_response(result.output)
|
||
|
||
async def _handle_plan_exec(self, task: TaskMessage) -> dict:
|
||
"""Plan-and-Execute mode: decompose task into plan, execute steps, replan if needed"""
|
||
from agentkit.core.plan_exec_engine import PlanExecEngine
|
||
|
||
variables = task.input_data.copy()
|
||
variables["task_type"] = task.task_type
|
||
|
||
if self._prompt_template:
|
||
rendered_messages = self._prompt_template.render(variables=variables)
|
||
else:
|
||
rendered_messages = [{"role": "user", "content": str(task.input_data)}]
|
||
|
||
system_prompt = None
|
||
user_messages = []
|
||
for msg in rendered_messages:
|
||
if msg["role"] == "system":
|
||
system_prompt = msg["content"]
|
||
else:
|
||
user_messages.append(msg)
|
||
|
||
if not user_messages:
|
||
user_messages.append({"role": "user", "content": str(task.input_data)})
|
||
|
||
cancellation_token = self._active_tokens.get(task.task_id)
|
||
timeout_seconds = float(task.timeout_seconds) if task.timeout_seconds > 0 else None
|
||
|
||
plan_exec_engine = PlanExecEngine(
|
||
llm_gateway=self._llm_gateway,
|
||
max_replans=2,
|
||
default_timeout=300.0,
|
||
)
|
||
|
||
result = await plan_exec_engine.execute(
|
||
messages=user_messages,
|
||
tools=self.get_tools() or None,
|
||
model=self._config.llm.get("model", "default") if self._config.llm else "default",
|
||
agent_name=self.name,
|
||
task_type=task.task_type,
|
||
system_prompt=system_prompt,
|
||
task_id=task.task_id,
|
||
cancellation_token=cancellation_token,
|
||
timeout_seconds=timeout_seconds,
|
||
)
|
||
|
||
return self._parse_llm_response(result.output)
|
||
|
||
async def _handle_reflexion(self, task: TaskMessage) -> dict:
|
||
"""Reflexion mode: ReAct + Evaluate + Reflect + Retry for high-precision tasks"""
|
||
from agentkit.core.reflexion import ReflexionEngine
|
||
|
||
variables = task.input_data.copy()
|
||
variables["task_type"] = task.task_type
|
||
|
||
if self._prompt_template:
|
||
rendered_messages = self._prompt_template.render(variables=variables)
|
||
else:
|
||
rendered_messages = [{"role": "user", "content": str(task.input_data)}]
|
||
|
||
system_prompt = None
|
||
user_messages = []
|
||
for msg in rendered_messages:
|
||
if msg["role"] == "system":
|
||
system_prompt = msg["content"]
|
||
else:
|
||
user_messages.append(msg)
|
||
|
||
if not user_messages:
|
||
user_messages.append({"role": "user", "content": str(task.input_data)})
|
||
|
||
cancellation_token = self._active_tokens.get(task.task_id)
|
||
timeout_seconds = float(task.timeout_seconds) if task.timeout_seconds > 0 else None
|
||
|
||
reflexion_engine = ReflexionEngine(
|
||
llm_gateway=self._llm_gateway,
|
||
max_steps=self._skill_config.max_steps if self._skill_config else 5,
|
||
max_reflections=3,
|
||
quality_threshold=0.7,
|
||
default_timeout=300.0,
|
||
)
|
||
|
||
result = await reflexion_engine.execute(
|
||
messages=user_messages,
|
||
tools=self.get_tools() or None,
|
||
model=self._config.llm.get("model", "default") if self._config.llm else "default",
|
||
agent_name=self.name,
|
||
task_type=task.task_type,
|
||
system_prompt=system_prompt,
|
||
task_id=task.task_id,
|
||
cancellation_token=cancellation_token,
|
||
timeout_seconds=timeout_seconds,
|
||
)
|
||
|
||
return self._parse_llm_response(result.output)
|
||
|
||
async def _handle_direct(self, task: TaskMessage) -> dict:
|
||
"""Direct mode: single LLM call without ReAct loop.
|
||
|
||
Renders the full prompt template and makes one LLM call via LLMGateway.
|
||
Falls back to _handle_llm_generate if no LLMGateway is available.
|
||
"""
|
||
if not self._llm_gateway:
|
||
return await self._handle_llm_generate(task)
|
||
|
||
# Build variables for prompt rendering
|
||
variables = task.input_data.copy()
|
||
variables["task_type"] = task.task_type
|
||
|
||
# Use PromptTemplate.render() to get full messages
|
||
if self._prompt_template:
|
||
rendered_messages = self._prompt_template.render(variables=variables)
|
||
else:
|
||
rendered_messages = [{"role": "user", "content": str(task.input_data)}]
|
||
|
||
# Make a single LLM call
|
||
model = self._config.llm.get("model", "default") if self._config.llm else "default"
|
||
response = await self._llm_gateway.chat(
|
||
messages=rendered_messages,
|
||
model=model,
|
||
agent_name=self.name,
|
||
task_type=task.task_type,
|
||
)
|
||
|
||
return self._parse_llm_response(response.content)
|
||
|
||
async def handle_task_with_feedback(self, task: TaskMessage, feedback: str) -> dict:
|
||
"""Re-execute task with quality feedback"""
|
||
enhanced_input = task.input_data.copy()
|
||
enhanced_input["quality_feedback"] = feedback
|
||
|
||
enhanced_task = TaskMessage(
|
||
task_id=task.task_id,
|
||
agent_name=task.agent_name,
|
||
task_type=task.task_type,
|
||
input_data=enhanced_input,
|
||
priority=task.priority,
|
||
created_at=task.created_at,
|
||
callback_url=task.callback_url,
|
||
timeout_seconds=task.timeout_seconds,
|
||
conversation_id=task.conversation_id,
|
||
)
|
||
return await self.handle_task(enhanced_task)
|
||
|
||
def _wrap_llm_client(self, llm_client: object):
|
||
"""Wrap legacy llm_client into LLMGateway"""
|
||
from agentkit.llm.gateway import LLMGateway
|
||
from agentkit.llm.protocol import LLMProvider, LLMRequest, LLMResponse, TokenUsage
|
||
|
||
class ClientProvider(LLMProvider):
|
||
"""Adapter: wraps legacy llm_client as an LLMProvider"""
|
||
|
||
def __init__(self, raw_client: object):
|
||
self._raw_client = raw_client
|
||
|
||
async def chat(self, request: LLMRequest) -> LLMResponse:
|
||
kwargs = dict(request._extra) if hasattr(request, "_extra") else {}
|
||
kwargs["model"] = request.model
|
||
kwargs["temperature"] = request.temperature
|
||
kwargs["max_tokens"] = request.max_tokens
|
||
|
||
if hasattr(self._raw_client, "chat"):
|
||
response = await self._raw_client.chat(messages=request.messages, **kwargs)
|
||
elif hasattr(self._raw_client, "create"):
|
||
response = await self._raw_client.create(messages=request.messages, **kwargs)
|
||
elif callable(self._raw_client):
|
||
response = await self._raw_client(messages=request.messages, **kwargs)
|
||
else:
|
||
raise ConfigValidationError(
|
||
agent_name="",
|
||
key="llm_client",
|
||
reason="LLM client must have 'chat'/'create' method or be callable",
|
||
)
|
||
|
||
# Normalize response to string
|
||
if isinstance(response, str):
|
||
content = response
|
||
elif isinstance(response, dict):
|
||
content = response.get("content", json.dumps(response))
|
||
elif hasattr(response, "content"):
|
||
content = response.content
|
||
else:
|
||
content = str(response)
|
||
|
||
return LLMResponse(
|
||
content=content,
|
||
model=request.model,
|
||
usage=TokenUsage(prompt_tokens=0, completion_tokens=0),
|
||
)
|
||
|
||
gateway = LLMGateway()
|
||
gateway.register_provider("wrapped", ClientProvider(llm_client))
|
||
return gateway
|
||
|
||
async def _handle_llm_generate(self, task: TaskMessage) -> dict:
|
||
"""LLM 生成模式：渲染 Prompt → 调用 LLM → 解析输出"""
|
||
if not self._prompt_template:
|
||
raise ConfigValidationError(
|
||
agent_name=self.name,
|
||
key="prompt",
|
||
reason="llm_generate mode requires prompt configuration",
|
||
)
|
||
|
||
# 渲染 Prompt
|
||
variables = task.input_data.copy()
|
||
variables["task_type"] = task.task_type
|
||
messages = self._prompt_template.render(variables=variables)
|
||
|
||
# 调用 LLM
|
||
if self._llm_client is None:
|
||
# 无 LLM 客户端时返回渲染后的 Prompt（降级模式）
|
||
return {
|
||
"mode": "llm_generate_no_client",
|
||
"messages": messages,
|
||
"note": "No LLM client configured, returning rendered prompt",
|
||
}
|
||
|
||
# 使用配置的 LLM 参数
|
||
llm_params = self._config.llm.copy()
|
||
response = await self._call_llm(messages, **llm_params)
|
||
return self._parse_llm_response(response)
|
||
|
||
async def _handle_tool_call(self, task: TaskMessage) -> dict:
|
||
"""工具调用模式：调用指定 Tool 并返回结果"""
|
||
if not self._tools:
|
||
raise ConfigValidationError(
|
||
agent_name=self.name,
|
||
key="tools",
|
||
reason="tool_call mode requires at least one bound tool",
|
||
)
|
||
|
||
# 使用第一个绑定的工具（或根据 task_type 匹配）
|
||
tool = self._resolve_tool(task)
|
||
result = await tool.safe_execute(**task.input_data)
|
||
return result
|
||
|
||
async def _handle_custom(self, task: TaskMessage) -> dict:
|
||
"""自定义模式：调用注册的 handler 函数"""
|
||
handler_name = self._config.custom_handler
|
||
if handler_name not in self._custom_handlers:
|
||
# 尝试动态导入
|
||
handler = self._import_handler(handler_name)
|
||
self._custom_handlers[handler_name] = handler
|
||
|
||
handler = self._custom_handlers[handler_name]
|
||
result = await handler(task)
|
||
if not isinstance(result, dict):
|
||
raise ConfigValidationError(
|
||
agent_name=self.name,
|
||
key="custom_handler",
|
||
reason=f"Custom handler '{handler_name}' must return dict, got {type(result)}",
|
||
)
|
||
return result
|
||
|
||
def _resolve_tool(self, task: TaskMessage) -> Tool:
|
||
"""根据任务类型解析要使用的工具"""
|
||
# 优先匹配 task_type 与 tool name
|
||
for tool in self._tools:
|
||
if task.task_type in tool.name or task.task_type.replace("_", "-") in tool.name:
|
||
return tool
|
||
|
||
# 回退到第一个工具
|
||
return self._tools[0]
|
||
|
||
async def _call_llm(self, messages: list[dict[str, str]], **kwargs) -> str:
|
||
"""调用 LLM 客户端"""
|
||
model = kwargs.pop("model", "default")
|
||
temperature = kwargs.pop("temperature", 0.7)
|
||
max_tokens = kwargs.pop("max_tokens", 2000)
|
||
|
||
# 标准化 LLM 客户端调用接口
|
||
if hasattr(self._llm_client, "chat"):
|
||
response = await self._llm_client.chat(
|
||
messages=messages,
|
||
model=model,
|
||
temperature=temperature,
|
||
max_tokens=max_tokens,
|
||
**kwargs,
|
||
)
|
||
elif hasattr(self._llm_client, "create"):
|
||
response = await self._llm_client.create(
|
||
messages=messages,
|
||
model=model,
|
||
temperature=temperature,
|
||
max_tokens=max_tokens,
|
||
**kwargs,
|
||
)
|
||
elif callable(self._llm_client):
|
||
response = await self._llm_client(
|
||
messages=messages,
|
||
model=model,
|
||
temperature=temperature,
|
||
max_tokens=max_tokens,
|
||
**kwargs,
|
||
)
|
||
else:
|
||
raise ConfigValidationError(
|
||
agent_name=self.name,
|
||
key="llm_client",
|
||
reason="LLM client must have 'chat'/'create' method or be callable",
|
||
)
|
||
|
||
# 提取文本内容
|
||
if isinstance(response, str):
|
||
return response
|
||
if isinstance(response, dict):
|
||
return response.get("content", str(response))
|
||
if hasattr(response, "content"):
|
||
return response.content
|
||
return str(response)
|
||
|
||
def _parse_llm_response(self, response: str) -> dict:
|
||
"""解析 LLM 响应为 dict"""
|
||
# 尝试直接解析 JSON
|
||
try:
|
||
return json.loads(response)
|
||
except (json.JSONDecodeError, TypeError):
|
||
pass
|
||
|
||
# 尝试提取 JSON 块
|
||
import re
|
||
|
||
json_match = re.search(r"```(?:json)?\s*\n?(.*?)\n?```", response, re.DOTALL)
|
||
if json_match:
|
||
try:
|
||
return json.loads(json_match.group(1))
|
||
except (json.JSONDecodeError, TypeError):
|
||
pass
|
||
|
||
# 降级：包装为文本结果
|
||
return {"text": response}
|
||
|
||
def _import_handler(self, dotted_path: str) -> Callable[..., Coroutine]:
|
||
"""动态导入自定义 handler"""
|
||
# Security: validate module prefix to prevent arbitrary code execution
|
||
if not any(dotted_path.startswith(prefix) for prefix in self._ALLOWED_HANDLER_PREFIXES):
|
||
raise ConfigValidationError(
|
||
agent_name=self.name,
|
||
key="custom_handler",
|
||
reason=f"Handler '{dotted_path}' is not in allowed module prefixes: {self._ALLOWED_HANDLER_PREFIXES}",
|
||
)
|
||
|
||
try:
|
||
module_path, func_name = dotted_path.rsplit(".", 1)
|
||
import importlib
|
||
|
||
module = importlib.import_module(module_path)
|
||
handler = getattr(module, func_name)
|
||
if not callable(handler):
|
||
raise ConfigValidationError(
|
||
agent_name=self.name,
|
||
key="custom_handler",
|
||
reason=f"'{dotted_path}' is not callable",
|
||
)
|
||
return handler
|
||
except (ImportError, AttributeError, ValueError) as e:
|
||
raise ConfigValidationError(
|
||
agent_name=self.name,
|
||
key="custom_handler",
|
||
reason=f"Failed to import custom handler '{dotted_path}': {e}",
|
||
)
|