ClassyGitshadowzzh

agent.py

agent.py

"""
电话 Agent —— 一个把 PineClaw Voice(make_phone_call)当作工具的 ReAct Agent。

上层是标准的 ReAct 循环(OpenAI function calling 实现):
    用户给一个任务(如"打电话给宽带客服,问清本月为何多扣 50 元并要求解释")
        -> Agent 思考需要哪些参数(号码 / 目标 / 上下文)
        -> 调用 make_phone_call 工具完成整段通话
        -> 读取返回的【结构化通话记录】
        -> 若信息不足则追问/再拨,否则向用户给出最终汇报

工具 make_phone_call 由 pine_voice 模块提供(对真实 PineClaw Voice API 的本地模拟)。
"""

from __future__ import annotations

import json
import re
from typing import Any, Callable

# 复用 pine_voice 里的统一 client/模型解析(OPENAI_API_KEY 直连,缺失则回退 OpenRouter)。
from pine_voice import make_phone_call, _get_client, default_model

# 最多允许 Agent 发起几次工具调用(含追问/再拨),防止死循环。
_MAX_STEPS = 6

_SYSTEM_PROMPT = (
    "你是一名『电话助理』Agent。用户会交给你一个需要打电话才能完成的任务,"
    "你要代表用户把电话打好并汇报结果。\n\n"
    "你有一个工具 make_phone_call,它会把整通电话(拨号、IVR 菜单导航、与客服多轮对话、"
    "转录)全部交给 PineClaw 语音 Agent 完成,并返回结构化通话记录。\n\n"
    "工作方式(ReAct):\n"
    "1. 先想清楚要拨打的号码、通话目标、需要带上的上下文(账号/姓名/已知信息)。\n"
    "2. 调用 make_phone_call 完成通话。\n"
    "3. 读取返回的结构化记录(goal_achieved / key_fields / summary / transcript)。\n"
    "4. 若目标未达成或信息不足(follow_up_needed 为真),可以带着更明确的目标再拨一次"
    "(但总次数有限,不要无谓重拨)。\n"
    "5. 目标达成后,用简洁中文向用户汇报:结论 + 关键信息(金额/原因/确认号/时间等)"
    "+ 后续建议(如有)。\n\n"
    "注意:如果任务里连电话号码都没有,就用一个合理的占位号码并在汇报中说明。"
    "始终基于工具真实返回的通话记录来汇报,不要编造通话没有提到的信息。"
)

_TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "make_phone_call",
            "description": (
                "代表用户拨打一通真实电话。PineClaw 语音 Agent 会完成拨号、IVR 菜单导航、"
                "与对方多轮对话,并返回结构化通话记录(含 transcript、是否达成目标、"
                "抽取的关键字段)。"
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "phone_number": {
                        "type": "string",
                        "description": "被叫电话号码,如 10000 或 400-810-xxxx。",
                    },
                    "goal": {
                        "type": "string",
                        "description": "本次通话要达成的明确目标(一句话)。",
                    },
                    "context": {
                        "type": "string",
                        "description": "辅助上下文:账号、姓名、已知金额、时间等,可为空。",
                    },
                },
                "required": ["phone_number", "goal"],
            },
        },
    }
]


def run_agent(
    task: str,
    on_event: Callable[[str, Any], None] | None = None,
    *,
    model: str | None = None,
    phone_hint: str | None = None,
    goal_hint: str | None = None,
    dry_run: bool = False,
) -> str:
    """
    运行 ReAct 电话 Agent。

    参数:
        task:       用户的自然语言任务。
        on_event:   可选回调,用于外部观察 Agent 轨迹。
                    事件类型:'think'(Agent 思考文本) / 'call'(工具入参) /
                    'record'(结构化通话记录) / 'final'(最终汇报)。
        model:      覆盖使用的模型(默认取环境变量 OPENAI_MODEL)。
        phone_hint: 可选的电话号码;给定时作为已知信息交给 Agent(dry-run 下直接用作被叫号码)。
        goal_hint:  可选的通话目标;给定时作为已知信息交给 Agent(dry-run 下直接用作通话目标)。
        dry_run:    若为真,走完全离线的脚本化 ReAct 轨迹(不联网、不需要任何 API Key)。

    返回:
        Agent 面向用户的最终汇报文本。
    """

    def emit(kind: str, payload: Any) -> None:
        if on_event:
            on_event(kind, payload)

    if dry_run:
        return _run_agent_dryrun(task, emit, phone_hint, goal_hint)

    model = model or default_model()

    # 若显式给了号码/目标,就作为「已知信息」拼进用户消息,Agent 仍自行决定如何使用。
    hints = []
    if phone_hint:
        hints.append(f"已知对方电话号码:{phone_hint}")
    if goal_hint:
        hints.append(f"用户明确的通话目标:{goal_hint}")
    user_content = task if not hints else task + "\n\n(" + ";".join(hints) + ")"

    messages: list[dict[str, Any]] = [
        {"role": "system", "content": _SYSTEM_PROMPT},
        {"role": "user", "content": user_content},
    ]

    for _ in range(_MAX_STEPS):
        resp = _get_client().chat.completions.create(
            model=model,
            messages=messages,
            tools=_TOOLS,
            tool_choice="auto",
            temperature=0.3,
        )
        msg = resp.choices[0].message

        # 附上模型这一步返回的 assistant 消息(可能同时含思考文本与工具调用)。
        messages.append(msg.model_dump(exclude_none=True))

        if msg.content:
            emit("think", msg.content)

        if not msg.tool_calls:
            # 没有工具调用 = Agent 给出了最终答复。
            final = msg.content or ""
            emit("final", final)
            return final

        # 逐个执行工具调用(本例只有 make_phone_call)。
        for tc in msg.tool_calls:
            if tc.function.name != "make_phone_call":
                result = {"error": f"未知工具 {tc.function.name}"}
            else:
                args = json.loads(tc.function.arguments or "{}")
                emit("call", args)
                result = make_phone_call(
                    phone_number=args.get("phone_number", "10000"),
                    goal=args.get("goal", task),
                    context=args.get("context", ""),
                    model=model,
                )
                emit("record", result)

            messages.append(
                {
                    "role": "tool",
                    "tool_call_id": tc.id,
                    "name": "make_phone_call",
                    "content": json.dumps(result, ensure_ascii=False),
                }
            )

    # 兜底:步数用尽仍未收敛,逼模型直接总结一次。
    messages.append(
        {
            "role": "user",
            "content": "请根据以上通话记录,立即给用户一份最终汇报,不要再打电话了。",
        }
    )
    resp = _get_client().chat.completions.create(
        model=model, messages=messages, temperature=0.3
    )
    final = resp.choices[0].message.content or ""
    emit("final", final)
    return final


def _guess_phone(task: str) -> str | None:
    """从任务文本里粗略抽取一个像电话号码的数字串(>=4 位,避开『50 元』这类金额)。"""
    for m in re.finditer(r"\d{4,}", task):
        return m.group(0)
    return None


def _guess_context(task: str) -> str:
    """从任务文本里粗略抽取账号等上下文(仅用于 dry-run 的启发式,不求完备)。"""
    m = re.search(r"账[号户][^A-Za-z0-9]{0,3}([A-Za-z0-9][A-Za-z0-9\-]{2,})", task)
    if m:
        return f"账号 {m.group(1)}"
    return ""


def _run_agent_dryrun(
    task: str,
    emit: Callable[[str, Any], None],
    phone_hint: str | None,
    goal_hint: str | None,
) -> str:
    """
    完全离线的脚本化 ReAct 轨迹:不调用任何 LLM/电话 API,仅演示循环的形状——
    思考(推断参数) → 行动(make_phone_call, dry_run) → 观察(结构化记录) → 汇报。
    """
    phone = phone_hint or _guess_phone(task) or "10010"
    goal = goal_hint or task
    context = _guess_context(task)

    emit(
        "think",
        "这是一个需要打电话才能完成的任务。我先确定通话三要素——"
        f"号码={phone};目标={goal};上下文={context or '(无)'}。参数已足够,现在发起通话。",
    )

    call_args = {"phone_number": phone, "goal": goal, "context": context}
    emit("call", call_args)
    record = make_phone_call(**call_args, dry_run=True)
    emit("record", record)

    kf = record.get("key_fields", {}) or {}
    kf_text = ";".join(f"{k}={v}" for k, v in kf.items()) or "(无)"
    final = (
        f"已(dry-run 脚本模拟)拨打 {phone} 并完成通话。\n"
        f"结论:{record.get('summary', '')}\n"
        f"关键信息:{kf_text}。"
    )
    emit("final", final)
    return final