跳转至

result

feishu.agent.result

ToolOutcome

Bases: str, Enum

工具执行结果的归一化处置（disposition）。

工具处理函数既可直接返回任意值（视同 COMPLETED），也可返回一个 feishu.agent.result.ToolResult 以显式声明处置。NEEDS_USER_AUTH 要求先引导用户完成 OAuth 授权：feishu.agent.loop.AgentEngine 据此发送一张 授权卡片并挂起本轮，待 OAuth callback 完成后恢复原工具调用。写操作的审批由工具的 requires_approval 在 分发**之前**统一挂起（见 feishu.agent.tools.Tool），不经由此枚举。由于继承自 str，枚举成员可直接与 字符串字面量比较。

示例：

Python Console Session
1
2
3
4
>>> ToolOutcome.NEEDS_USER_AUTH == "needs_user_auth"
True
>>> ToolOutcome("completed") is ToolOutcome.COMPLETED
True
源代码位于： feishu/agent/result.py
Python
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
class ToolOutcome(str, Enum):
    r"""
    工具执行结果的归一化处置（disposition）。

    工具处理函数既可直接返回任意值（视同 `COMPLETED`），也可返回一个 [feishu.agent.result.ToolResult][]
    以显式声明处置。`NEEDS_USER_AUTH` 要求先引导用户完成 OAuth 授权：[feishu.agent.loop.AgentEngine][] 据此发送一张
    授权卡片并挂起本轮，待 OAuth callback 完成后恢复原工具调用。写操作的审批由工具的 `requires_approval` 在
    分发**之前**统一挂起（见 [feishu.agent.tools.Tool][]），不经由此枚举。由于继承自 `str`，枚举成员可直接与
    字符串字面量比较。

    Examples:
        >>> ToolOutcome.NEEDS_USER_AUTH == "needs_user_auth"
        True
        >>> ToolOutcome("completed") is ToolOutcome.COMPLETED
        True
    """

    COMPLETED = "completed"
    FAILED = "failed"
    BLOCKED = "blocked"
    NEEDS_USER_AUTH = "needs_user_auth"
    CANCELLED = "cancelled"
    INFORMATIONAL = "informational"

ToolResult dataclass

工具处理函数的结构化返回值，向 feishu.agent.loop.AgentEngine 声明处置与回传内容。

多数工具可直接返回原始值；需要声明处置时返回本类型：NEEDS_USER_AUTH 可随附 auth_scopes 与 authorize_url（旧式回退链接）。content 是回传给模型的工具结果文本/对象，is_error 为 True 时模型 据此调整后续行为。写操作的二次确认由工具的 requires_approval 在分发前统一处理，不经由本返回值。

示例：

Python Console Session
1
2
3
4
5
>>> ok = ToolResult(outcome=ToolOutcome.COMPLETED, content="已列出 3 个日程")
>>> ok.outcome
<ToolOutcome.COMPLETED: 'completed'>
>>> ok.is_error
False
源代码位于： feishu/agent/result.py
Python
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
@dataclass(slots=True)
class ToolResult:
    r"""
    工具处理函数的结构化返回值，向 [feishu.agent.loop.AgentEngine][] 声明处置与回传内容。

    多数工具可直接返回原始值；需要声明处置时返回本类型：`NEEDS_USER_AUTH` 可随附 `auth_scopes` 与
    `authorize_url`（旧式回退链接）。`content` 是回传给模型的工具结果文本/对象，`is_error` 为 `True` 时模型
    据此调整后续行为。写操作的二次确认由工具的 `requires_approval` 在分发前统一处理，不经由本返回值。

    Examples:
        >>> ok = ToolResult(outcome=ToolOutcome.COMPLETED, content="已列出 3 个日程")
        >>> ok.outcome
        <ToolOutcome.COMPLETED: 'completed'>
        >>> ok.is_error
        False
    """

    outcome: ToolOutcome
    content: Any = None
    authorize_url: str | None = None
    auth_scopes: tuple[str, ...] = ()
    is_error: bool = False

coerce_tool_result

Python
coerce_tool_result(result: Any) -> tuple[str, bool, ToolResult | None]

归一化工具返回值为 (content_text, is_error, structured_result)。

源代码位于： feishu/agent/result.py
Python
79
80
81
82
83
84
85
86
87
88
89
def coerce_tool_result(result: Any) -> tuple[str, bool, ToolResult | None]:
    r"""归一化工具返回值为 `(content_text, is_error, structured_result)`。"""
    if isinstance(result, ToolResult):
        is_error = result.is_error or result.outcome not in (ToolOutcome.COMPLETED, ToolOutcome.INFORMATIONAL)
        text = _stringify(result.content) if result.content is not None else ""
        if result.authorize_url:
            text = f"{text}\n授权链接：{result.authorize_url}".strip()
        return text, is_error, result
    if result is None:
        return "", False, None
    return _stringify(result), False, None