Agent调用工具时如何优雅输出描述：新手入门指南与最佳实践

1次阅读

没有评论

共计 2434 个字符，预计需要花费 7 分钟才能阅读完成。

当我们开发 Agent 调用工具时，输出的描述信息往往容易被忽视，导致后期维护和调试困难。以下是新手常见的几个问题：

格式混乱 ：不同工具或模块输出的描述格式不一致，有的用 JSON，有的用纯文本，甚至同一工具在不同情况下输出格式也不同。
缺乏上下文 ：当出现错误时，仅返回简单的错误代码，没有说明具体是哪个步骤出了问题，或者缺少必要的环境信息。
错误信息不明确 ：错误描述过于技术化或过于简单，既不利于开发者调试，也不利于终端用户理解。

这些问题的根源在于缺乏统一的输出规范和设计原则。下面我们就来探讨如何解决这些问题。

好的输出描述应该遵循以下结构化设计原则：

基础元数据 ：
时间戳（timestamp）：记录操作发生的时间
请求 ID（request_id）：唯一标识每次调用
状态码（status_code）：标准化的操作结果状态
核心内容 ：
操作描述（description）：人类可读的操作说明
业务数据（data）：返回的具体业务内容
执行详情（details）：详细的执行过程记录
扩展信息 ：
执行耗时（duration）：操作执行时间
环境信息（environment）：运行环境标识
版本信息（version）：接口或工具版本

下面是一个 Python 实现的标准化响应对象示例：

import time
import uuid
from datetime import datetime
from typing import Any, Dict, Optional

class StandardResponse:
    """标准化响应对象"""
    def __init__(self):
        self.timestamp = datetime.utcnow().isoformat() + 'Z'
        self.request_id = str(uuid.uuid4())
        self.status = "success"  # or "error"
        self.code = 200          # HTTP 状态码
        self.message = ""        # 人类可读的消息
        self.data = None         # 返回的业务数据
        self.details = []        # 执行详情
        self.duration = 0        # 执行耗时 (毫秒)

    def set_error(self, code: int, message: str):
        """设置错误响应"""
        self.status = "error"
        self.code = code
        self.message = message
        return self

    def add_detail(self, detail: str):
        """添加执行详情"""
        self.details.append(detail)
        return self

    def set_data(self, data: Any):
        """设置返回数据"""
        self.data = data
        return self

    def to_dict(self) -> Dict:
        """转换为字典格式"""
        return {
            "timestamp": self.timestamp,
            "request_id": self.request_id,
            "status": self.status,
            "code": self.code,
            "message": self.message,
            "data": self.data,
            "details": self.details,
            "duration": self.duration
        }

# 使用示例
def process_data(input_data):
    """处理数据示例函数"""
    response = StandardResponse()
    start_time = time.time()

    try:
        # 记录处理步骤
        response.add_detail("开始验证输入数据")
        if not input_data:
            raise ValueError("输入数据不能为空")

        response.add_detail("数据验证通过")
        # 模拟业务处理
        processed_data = {"result": len(input_data)}
        response.set_data(processed_data)

    except Exception as e:
        response.set_error(400, str(e))
        response.add_detail(f"处理失败: {str(e)}")
    finally:
        response.duration = int((time.time() - start_time) * 1000)

    return response.to_dict()

良好的错误处理应该：