Agent/gateway/client/python/tools.py

"""
Gateway 通用工具函数

这些函数不依赖任何特定的 Agent 框架，可以被任何 Agent 直接使用。
各框架可以将这些函数包装成自己的工具格式。
"""

import uuid
from typing import Any, Dict, List, Optional

from .client import GatewayClient, AgentCard


async def send_message(
    gateway_url: str,
    from_agent_id: str,
    to_agent_id: str,
    message: str,
    conversation_id: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None
) -> Dict[str, Any]:
    """
    发送消息到其他 Agent（通用函数）

    Args:
        gateway_url: Gateway 地址
        from_agent_id: 发送方 Agent ID
        to_agent_id: 接收方 Agent ID
        message: 消息内容（文本）
        conversation_id: 对话 ID（可选，不提供则新建）
        metadata: 元数据

    Returns:
        发送结果，包含 conversation_id, message_id 等
    """
    # 生成对话 ID
    conv_id = conversation_id or f"conv-{uuid.uuid4()}"

    # 创建临时客户端
    agent_card = AgentCard(
        agent_id=from_agent_id,
        agent_name=from_agent_id
    )

    async with GatewayClient(gateway_url=gateway_url, agent_card=agent_card) as client:
        result = await client.send_message(
            to_agent_id=to_agent_id,
            content=[{"type": "text", "text": message}],
            conversation_id=conv_id,
            metadata=metadata
        )

    return {
        "conversation_id": conv_id,
        "message_id": result.get("message_id"),
        "status": result.get("status", "sent"),
        "to_agent": to_agent_id
    }


async def send_multimodal_message(
    gateway_url: str,
    from_agent_id: str,
    to_agent_id: str,
    content: List[Dict[str, Any]],
    conversation_id: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None
) -> Dict[str, Any]:
    """
    发送多模态消息到其他 Agent（通用函数）

    Args:
        gateway_url: Gateway 地址
        from_agent_id: 发送方 Agent ID
        to_agent_id: 接收方 Agent ID
        content: MAMP 格式的多模态内容
        conversation_id: 对话 ID（可选）
        metadata: 元数据

    Returns:
        发送结果
    """
    conv_id = conversation_id or f"conv-{uuid.uuid4()}"

    agent_card = AgentCard(
        agent_id=from_agent_id,
        agent_name=from_agent_id
    )

    async with GatewayClient(gateway_url=gateway_url, agent_card=agent_card) as client:
        result = await client.send_message(
            to_agent_id=to_agent_id,
            content=content,
            conversation_id=conv_id,
            metadata=metadata
        )

    return {
        "conversation_id": conv_id,
        "message_id": result.get("message_id"),
        "status": result.get("status", "sent"),
        "to_agent": to_agent_id
    }


async def list_online_agents(
    gateway_url: str,
    agent_type: Optional[str] = None
) -> List[Dict[str, Any]]:
    """
    查询在线 Agent 列表（通用函数）

    Args:
        gateway_url: Gateway 地址
        agent_type: 过滤 Agent 类型（可选）

    Returns:
        在线 Agent 列表
    """
    # 创建临时客户端（用于查询）
    agent_card = AgentCard(
        agent_id="query-client",
        agent_name="Query Client"
    )

    async with GatewayClient(gateway_url=gateway_url, agent_card=agent_card) as client:
        agents = await client.list_agents(online_only=True, agent_type=agent_type)

    return agents


async def get_agent_status(
    gateway_url: str,
    agent_id: str
) -> Dict[str, Any]:
    """
    查询指定 Agent 的在线状态（通用函数）

    Args:
        gateway_url: Gateway 地址
        agent_id: Agent ID

    Returns:
        Agent 状态信息
    """
    agent_card = AgentCard(
        agent_id="query-client",
        agent_name="Query Client"
    )

    async with GatewayClient(gateway_url=gateway_url, agent_card=agent_card) as client:
        status = await client.get_agent_status(agent_id)

    return status


async def register_agent(
    gateway_url: str,
    agent_id: str,
    agent_name: str,
    agent_type: Optional[str] = None,
    capabilities: Optional[List[str]] = None,
    description: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None
) -> GatewayClient:
    """
    注册 Agent 到 Gateway（通用函数）

    Args:
        gateway_url: Gateway 地址
        agent_id: Agent ID
        agent_name: Agent 名称
        agent_type: Agent 类型
        capabilities: Agent 能力列表
        description: Agent 描述
        metadata: 元数据

    Returns:
        已连接的 GatewayClient 实例（需要调用方管理生命周期）
    """
    agent_card = AgentCard(
        agent_id=agent_id,
        agent_name=agent_name,
        agent_type=agent_type,
        capabilities=capabilities or [],
        description=description,
        metadata=metadata or {}
    )

    client = GatewayClient(gateway_url=gateway_url, agent_card=agent_card)
    await client.connect()

    return client