aiagent/backend/app/agent_runtime/schemas.py

"""
Agent Runtime 配置与数据结构 Schema
"""
from __future__ import annotations

from typing import Any, Dict, List, Optional
from pydantic import BaseModel, Field


class AgentToolConfig(BaseModel):
    """Agent 可用工具配置"""
    # 若为空列表则使用全部已注册工具
    include_tools: List[str] = Field(default_factory=list, description="允许的工具名称白名单")
    exclude_tools: List[str] = Field(default_factory=list, description="排除的工具名称黑名单")


class AgentMemoryConfig(BaseModel):
    """Agent 记忆配置"""
    enabled: bool = True
    max_history_messages: int = 20  # 注入 LLM 的上文最大消息数
    session_key: Optional[str] = None  # 会话标识，默认自动生成
    persist_to_db: bool = True       # 是否写入 MySQL 长期记忆
    vector_memory_enabled: bool = True  # 是否启用向量记忆（语义检索）
    vector_memory_top_k: int = 5       # 向量检索 Top-K
    learning_enabled: bool = True     # 是否启用自主学习（工具模式学习）


class AgentLLMConfig(BaseModel):
    """Agent 模型配置"""
    provider: str = "openai"        # openai / deepseek
    model: str = "gpt-4o-mini"
    temperature: float = 0.7
    max_tokens: Optional[int] = None
    api_key: Optional[str] = None
    base_url: Optional[str] = None
    max_iterations: int = 10        # ReAct 循环最大步数
    request_timeout: float = 120.0
    extra_body: Optional[Dict[str, Any]] = None


class AgentBudgetConfig(BaseModel):
    """Agent 执行预算配置"""
    max_llm_invocations: int = 200   # LLM 调用次数上限
    max_tool_calls: int = 500        # 工具调用次数上限


class AgentConfig(BaseModel):
    """Agent 完整配置"""
    name: str = "default_agent"
    system_prompt: str = "你是一个有用的AI助手。请使用可用工具来帮助用户完成任务。"
    llm: AgentLLMConfig = Field(default_factory=AgentLLMConfig)
    tools: AgentToolConfig = Field(default_factory=AgentToolConfig)
    memory: AgentMemoryConfig = Field(default_factory=AgentMemoryConfig)
    budget: AgentBudgetConfig = Field(default_factory=AgentBudgetConfig)
    user_id: Optional[str] = None
    # 持久记忆 / 向量记忆的 scope_id；不设时沿用 user_id 或 name（易与其他 Agent 串记忆）
    memory_scope_id: Optional[str] = None


class AgentMessage(BaseModel):
    """Agent 对话消息"""
    role: str  # user / assistant / tool
    content: str
    tool_calls: Optional[List[Dict[str, Any]]] = None
    tool_call_id: Optional[str] = None
    name: Optional[str] = None


class AgentStep(BaseModel):
    """Agent 单步执行记录（用于执行追踪）"""
    iteration: int = Field(..., description="第几步")
    type: str = Field(..., description="步骤类型: think / tool_call / tool_result / final")
    content: str = Field(default="", description="步骤内容")
    tool_name: Optional[str] = Field(default=None, description="工具名称（tool_call/tool_result 类型时）")
    tool_input: Optional[Dict[str, Any]] = Field(default=None, description="工具输入参数")
    tool_result: Optional[str] = Field(default=None, description="工具执行结果")
    reasoning: Optional[str] = Field(default=None, description="思考过程")


class AgentResult(BaseModel):
    """Agent 执行结果"""
    success: bool = True
    content: str = ""
    truncated: bool = False
    iterations_used: int = 0
    tool_calls_made: int = 0
    error: Optional[str] = None
    steps: List[AgentStep] = Field(default_factory=list, description="执行追踪步骤详情")