calendar

feishu.agent.toolkit.calendar

日历工具工厂：列出日程、创建日程（需审批）、查询忙闲。详见 feishu.agent.toolkit。

list_calendar_events

Python

list_calendar_events(*, description: str, name: str = 'list_calendar_events', locale: str = 'zh-CN', timezone: str = 'Asia/Shanghai', as_user: bool = True, auth_scopes: Sequence[str] = ()) -> Tool

读类工厂：列出用户日程，返回一个 feishu.agent.tools.Tool。

处理函数解析日历（缺省取主日历），把 ISO 时间经 feishu.calendar.unix_seconds 转为接口所需的秒级 时间戳，再调用 client.calendar.events.list(calendar_id, start_time=..., end_time=...)。

参数：

名称	类型	描述	默认
description	str	工具描述（产品本地化文案）。	必需
name	str	工具名。默认为 "list_calendar_events"。	'list_calendar_events'
locale	str	本地化标识。默认为 "zh-CN"。	'zh-CN'
timezone	str	ISO 时间换算所用时区。默认为 "Asia/Shanghai"。	'Asia/Shanghai'
as_user	bool	是否以请求用户身份读取。默认为 True。	True
auth_scopes	Sequence[str]	缺少授权时申请的飞书权限范围。	()

示例：

>>> tool = list_calendar_events(description="查看我的日程")
>>> tool.name, tool.requires_approval
('list_calendar_events', False)

源代码位于： feishu/agent/toolkit/calendar.py

def list_calendar_events(
    *,
    description: str,
    name: str = "list_calendar_events",
    locale: str = "zh-CN",
    timezone: str = "Asia/Shanghai",
    as_user: bool = True,
    auth_scopes: Sequence[str] = (),
) -> Tool:
    r"""
    读类工厂：列出用户日程，返回一个 [feishu.agent.tools.Tool][]。

    处理函数解析日历（缺省取主日历），把 ISO 时间经 [feishu.calendar.unix_seconds][] 转为接口所需的秒级
    时间戳，再调用 `client.calendar.events.list(calendar_id, start_time=..., end_time=...)`。

    Args:
        description: 工具描述（产品本地化文案）。
        name: 工具名。默认为 `"list_calendar_events"`。
        locale: 本地化标识。默认为 `"zh-CN"`。
        timezone: ISO 时间换算所用时区。默认为 `"Asia/Shanghai"`。
        as_user: 是否以请求用户身份读取。默认为 `True`。
        auth_scopes: 缺少授权时申请的飞书权限范围。

    Examples:
        >>> tool = list_calendar_events(description="查看我的日程")
        >>> tool.name, tool.requires_approval
        ('list_calendar_events', False)
    """
    input_schema: dict[str, Any] = {
        "type": "object",
        "properties": {
            "time_min": {"type": "string", "description": "ISO 8601 start of the range"},
            "time_max": {"type": "string", "description": "ISO 8601 end of the range"},
            "calendar_id": {"type": "string", "description": "calendar id; defaults to the user's primary calendar"},
            "max_items": {"type": "integer", "description": "max events to return"},
        },
        "required": ["time_min", "time_max"],
        "additionalProperties": False,
    }

    async def handler(**arguments: Any) -> ToolResult:
        client = await resolve_client(as_user=as_user)
        if client is None:
            return needs_user_auth(auth_scopes)
        calendar_id = await _resolve_calendar_id(client, arguments.get("calendar_id"))
        events = await client.calendar.events.list(
            calendar_id,
            start_time=str(unix_seconds(arguments["time_min"], timezone=timezone)),
            end_time=str(unix_seconds(arguments["time_max"], timezone=timezone)),
            max_items=int(arguments.get("max_items") or 20),
        )
        return ToolResult(ToolOutcome.COMPLETED, content=events)

    return Tool(name=name, description=description, input_schema=input_schema, handler=handler)

create_calendar_event

Python

create_calendar_event(*, description: str, name: str = 'create_calendar_event', locale: str = 'zh-CN', timezone: str = 'Asia/Shanghai', requires_approval: bool = True, as_user: bool = True, auth_scopes: Sequence[str] = ()) -> Tool

写类工厂：创建日程，返回一个需审批的 feishu.agent.tools.Tool。

处理函数解析日历（缺省取主日历），用 feishu.calendar.calendar_event 构造事件体，再调用 client.calendar.events.create(calendar_id, event)。requires_approval=True 时由 feishu.agent.loop.Agent 先发审批卡片，用户批准后才执行。

示例：

>>> tool = create_calendar_event(description="创建日程")
>>> tool.name, tool.requires_approval
('create_calendar_event', True)

源代码位于： feishu/agent/toolkit/calendar.py

def create_calendar_event(
    *,
    description: str,
    name: str = "create_calendar_event",
    locale: str = "zh-CN",
    timezone: str = "Asia/Shanghai",
    requires_approval: bool = True,
    as_user: bool = True,
    auth_scopes: Sequence[str] = (),
) -> Tool:
    r"""
    写类工厂：创建日程，返回一个需审批的 [feishu.agent.tools.Tool][]。

    处理函数解析日历（缺省取主日历），用 [feishu.calendar.calendar_event][] 构造事件体，再调用
    `client.calendar.events.create(calendar_id, event)`。`requires_approval=True` 时由
    [feishu.agent.loop.Agent][] 先发审批卡片，用户批准后才执行。

    Examples:
        >>> tool = create_calendar_event(description="创建日程")
        >>> tool.name, tool.requires_approval
        ('create_calendar_event', True)
    """
    input_schema: dict[str, Any] = {
        "type": "object",
        "properties": {
            "summary": {"type": "string"},
            "start": {"type": "string", "description": "ISO 8601 start"},
            "end": {"type": "string", "description": "ISO 8601 end"},
            "description": {"type": "string"},
            "location": {"type": "string"},
            "calendar_id": {"type": "string", "description": "calendar id; defaults to the user's primary calendar"},
        },
        "required": ["summary", "start", "end"],
        "additionalProperties": False,
    }

    async def handler(**arguments: Any) -> ToolResult:
        # Runs only AFTER the user approves the confirmation card; perform the write directly.
        client = await resolve_client(as_user=as_user)
        if client is None:
            return needs_user_auth(auth_scopes)
        calendar_id = await _resolve_calendar_id(client, arguments.get("calendar_id"))
        event = calendar_event(
            summary=arguments["summary"],
            start_time=arguments["start"],
            end_time=arguments["end"],
            timezone=timezone,
            description=arguments.get("description"),
            location=arguments.get("location"),
        )
        result = await client.calendar.events.create(calendar_id, event)
        return ToolResult(ToolOutcome.COMPLETED, content=result)

    return Tool(
        name=name,
        description=description,
        input_schema=input_schema,
        handler=handler,
        requires_approval=requires_approval,
    )

query_calendar_free_busy

Python

query_calendar_free_busy(*, description: str, name: str = 'query_calendar_free_busy', locale: str = 'zh-CN', timezone: str = 'Asia/Shanghai', as_user: bool = True, auth_scopes: Sequence[str] = ()) -> Tool

读类工厂：查询「请求用户本人」的忙闲信息，返回一个 feishu.agent.tools.Tool。

最小权限（zero-trust）：本工具只查询发起请求的用户本人，主体身份取自 feishu.agent.context.ToolContext.requesting_user，模型无法指向他人。查询会议室忙闲请改用 feishu.agent.toolkit.rooms.query_meeting_room_free_busy。

参数：

名称	类型	描述	默认
description	str	工具描述（产品本地化文案）。	必需
name	str	工具名。默认为 "query_calendar_free_busy"。	'query_calendar_free_busy'
locale	str	本地化标识。默认为 "zh-CN"。	'zh-CN'
timezone	str	时间转换所用时区。默认为 "Asia/Shanghai"。	'Asia/Shanghai'
as_user	bool	是否以请求用户身份读取。默认为 True。	True
auth_scopes	Sequence[str]	缺少授权时申请的飞书权限范围。	()

示例：

>>> tool = query_calendar_free_busy(description="查询忙闲")
>>> tool.name, tool.requires_approval
('query_calendar_free_busy', False)

源代码位于： feishu/agent/toolkit/calendar.py

def query_calendar_free_busy(
    *,
    description: str,
    name: str = "query_calendar_free_busy",
    locale: str = "zh-CN",
    timezone: str = "Asia/Shanghai",
    as_user: bool = True,
    auth_scopes: Sequence[str] = (),
) -> Tool:
    r"""
    读类工厂：查询「请求用户本人」的忙闲信息，返回一个 [feishu.agent.tools.Tool][]。

    最小权限（zero-trust）：本工具只查询发起请求的用户本人，主体身份取自
    [feishu.agent.context.ToolContext.requesting_user][]，模型无法指向他人。查询会议室忙闲请改用
    [feishu.agent.toolkit.rooms.query_meeting_room_free_busy][]。

    Args:
        description: 工具描述（产品本地化文案）。
        name: 工具名。默认为 `"query_calendar_free_busy"`。
        locale: 本地化标识。默认为 `"zh-CN"`。
        timezone: 时间转换所用时区。默认为 `"Asia/Shanghai"`。
        as_user: 是否以请求用户身份读取。默认为 `True`。
        auth_scopes: 缺少授权时申请的飞书权限范围。

    Examples:
        >>> tool = query_calendar_free_busy(description="查询忙闲")
        >>> tool.name, tool.requires_approval
        ('query_calendar_free_busy', False)
    """
    input_schema: dict[str, Any] = {
        "type": "object",
        "properties": {
            "time_min": {"type": "string", "description": "ISO 8601 start of the range"},
            "time_max": {"type": "string", "description": "ISO 8601 end of the range"},
        },
        "required": ["time_min", "time_max"],
        "additionalProperties": False,
    }

    async def handler(**arguments: Any) -> ToolResult:
        client = await resolve_client(as_user=as_user)
        if client is None:
            return needs_user_auth(auth_scopes)
        # Least-privilege: only ever query the requesting user's own free/busy, never an arbitrary user.
        subject = requesting_user_id("open_id")
        if not subject:
            return ToolResult(
                ToolOutcome.BLOCKED, content="cannot resolve the requesting user's identity", is_error=True
            )
        body = freebusy_body(
            time_min=arguments["time_min"],
            time_max=arguments["time_max"],
            user_id=subject,
            timezone=timezone,
        )
        freebusy = await client.calendar.freebusy.query(body)
        return ToolResult(ToolOutcome.COMPLETED, content=freebusy)

    return Tool(name=name, description=description, input_schema=input_schema, handler=handler)

update_calendar_event

Python

update_calendar_event(*, description: str, name: str = 'update_calendar_event', locale: str = 'zh-CN', timezone: str = 'Asia/Shanghai', requires_approval: bool = True, as_user: bool = True, auth_scopes: Sequence[str] = ()) -> Tool

写类工厂：改期 / 编辑已有日程，返回一个需审批的 feishu.agent.tools.Tool。

处理函数解析日历（缺省取主日历），仅依据模型显式传入的字段构造**增量更新体**——未传入的字段保持 不变——再调用 client.calendar.events.update(calendar_id, event_id, event)。时间字段经 feishu.calendar.calendar_time 归一化（与 feishu.calendar.calendar_event 同形），location 以 {"name": ...} 写入。requires_approval=True 时由 feishu.agent.loop.Agent 先发审批卡片， 用户批准后处理函数才执行写入。

参数：

名称	类型	描述	默认
description	str	工具描述（产品本地化文案）。	必需
name	str	工具名。默认为 "update_calendar_event"。	'update_calendar_event'
locale	str	本地化标识。默认为 "zh-CN"。	'zh-CN'
timezone	str	ISO 时间换算所用时区。默认为 "Asia/Shanghai"。	'Asia/Shanghai'
requires_approval	bool	是否需用户审批后执行。默认为 True。	True
as_user	bool	是否以请求用户身份写入。默认为 True。	True
auth_scopes	Sequence[str]	缺少授权时申请的飞书权限范围。	()

示例：

>>> tool = update_calendar_event(description="改期日程")
>>> tool.name, tool.requires_approval
('update_calendar_event', True)

源代码位于： feishu/agent/toolkit/calendar.py

def update_calendar_event(
    *,
    description: str,
    name: str = "update_calendar_event",
    locale: str = "zh-CN",
    timezone: str = "Asia/Shanghai",
    requires_approval: bool = True,
    as_user: bool = True,
    auth_scopes: Sequence[str] = (),
) -> Tool:
    r"""
    写类工厂：改期 / 编辑已有日程，返回一个需审批的 [feishu.agent.tools.Tool][]。

    处理函数解析日历（缺省取主日历），仅依据模型显式传入的字段构造**增量更新体**——未传入的字段保持
    不变——再调用 `client.calendar.events.update(calendar_id, event_id, event)`。时间字段经
    [feishu.calendar.calendar_time][] 归一化（与 [feishu.calendar.calendar_event][] 同形），`location`
    以 `{"name": ...}` 写入。`requires_approval=True` 时由 [feishu.agent.loop.Agent][] 先发审批卡片，
    用户批准后处理函数才执行写入。

    Args:
        description: 工具描述（产品本地化文案）。
        name: 工具名。默认为 `"update_calendar_event"`。
        locale: 本地化标识。默认为 `"zh-CN"`。
        timezone: ISO 时间换算所用时区。默认为 `"Asia/Shanghai"`。
        requires_approval: 是否需用户审批后执行。默认为 `True`。
        as_user: 是否以请求用户身份写入。默认为 `True`。
        auth_scopes: 缺少授权时申请的飞书权限范围。

    Examples:
        >>> tool = update_calendar_event(description="改期日程")
        >>> tool.name, tool.requires_approval
        ('update_calendar_event', True)
    """
    input_schema: dict[str, Any] = {
        "type": "object",
        "properties": {
            "event_id": {"type": "string", "description": "event id to update"},
            "summary": {"type": "string"},
            "start": {"type": "string", "description": "ISO 8601 start"},
            "end": {"type": "string", "description": "ISO 8601 end"},
            "description": {"type": "string"},
            "location": {"type": "string"},
            "calendar_id": {"type": "string", "description": "calendar id; defaults to the user's primary calendar"},
        },
        "required": ["event_id"],
        "additionalProperties": False,
    }

    async def handler(**arguments: Any) -> ToolResult:
        # Runs only AFTER the user approves the confirmation card; perform the write directly.
        client = await resolve_client(as_user=as_user)
        if client is None:
            return needs_user_auth(auth_scopes)
        calendar_id = await _resolve_calendar_id(client, arguments.get("calendar_id"))
        # Incremental patch: include only fields the model explicitly supplied; omit the rest.
        event: dict[str, Any] = {}
        if arguments.get("summary") is not None:
            event["summary"] = arguments["summary"]
        if arguments.get("start") is not None:
            event["start_time"] = calendar_time(arguments["start"], timezone=timezone)
        if arguments.get("end") is not None:
            event["end_time"] = calendar_time(arguments["end"], timezone=timezone)
        if arguments.get("description") is not None:
            event["description"] = arguments["description"]
        if arguments.get("location") is not None:
            event["location"] = {"name": arguments["location"]}
        result = await client.calendar.events.update(calendar_id, arguments["event_id"], event)
        return ToolResult(ToolOutcome.COMPLETED, content=result)

    return Tool(
        name=name,
        description=description,
        input_schema=input_schema,
        handler=handler,
        requires_approval=requires_approval,
    )

cancel_calendar_event

Python

cancel_calendar_event(*, description: str, name: str = 'cancel_calendar_event', locale: str = 'zh-CN', requires_approval: bool = True, as_user: bool = True, auth_scopes: Sequence[str] = ()) -> Tool

写类工厂：取消（删除）已有日程，返回一个需审批的 feishu.agent.tools.Tool。

处理函数解析日历（缺省取主日历），再调用 client.calendar.events.delete(calendar_id, event_id)。 requires_approval=True 时由 feishu.agent.loop.Agent 先发审批卡片，用户批准后处理函数才执行删除。

参数：

名称	类型	描述	默认
description	str	工具描述（产品本地化文案）。	必需
name	str	工具名。默认为 "cancel_calendar_event"。	'cancel_calendar_event'
locale	str	本地化标识。默认为 "zh-CN"。	'zh-CN'
requires_approval	bool	是否需用户审批后执行。默认为 True。	True
as_user	bool	是否以请求用户身份写入。默认为 True。	True
auth_scopes	Sequence[str]	缺少授权时申请的飞书权限范围。	()

示例：

>>> tool = cancel_calendar_event(description="取消日程")
>>> tool.name, tool.requires_approval
('cancel_calendar_event', True)

源代码位于： feishu/agent/toolkit/calendar.py

def cancel_calendar_event(
    *,
    description: str,
    name: str = "cancel_calendar_event",
    locale: str = "zh-CN",
    requires_approval: bool = True,
    as_user: bool = True,
    auth_scopes: Sequence[str] = (),
) -> Tool:
    r"""
    写类工厂：取消（删除）已有日程，返回一个需审批的 [feishu.agent.tools.Tool][]。

    处理函数解析日历（缺省取主日历），再调用 `client.calendar.events.delete(calendar_id, event_id)`。
    `requires_approval=True` 时由 [feishu.agent.loop.Agent][] 先发审批卡片，用户批准后处理函数才执行删除。

    Args:
        description: 工具描述（产品本地化文案）。
        name: 工具名。默认为 `"cancel_calendar_event"`。
        locale: 本地化标识。默认为 `"zh-CN"`。
        requires_approval: 是否需用户审批后执行。默认为 `True`。
        as_user: 是否以请求用户身份写入。默认为 `True`。
        auth_scopes: 缺少授权时申请的飞书权限范围。

    Examples:
        >>> tool = cancel_calendar_event(description="取消日程")
        >>> tool.name, tool.requires_approval
        ('cancel_calendar_event', True)
    """
    input_schema: dict[str, Any] = {
        "type": "object",
        "properties": {
            "event_id": {"type": "string", "description": "event id to delete"},
            "calendar_id": {"type": "string", "description": "calendar id; defaults to the user's primary calendar"},
        },
        "required": ["event_id"],
        "additionalProperties": False,
    }

    async def handler(**arguments: Any) -> ToolResult:
        # Runs only AFTER the user approves the confirmation card; perform the write directly.
        client = await resolve_client(as_user=as_user)
        if client is None:
            return needs_user_auth(auth_scopes)
        calendar_id = await _resolve_calendar_id(client, arguments.get("calendar_id"))
        result = await client.calendar.events.delete(calendar_id, arguments["event_id"])
        return ToolResult(ToolOutcome.COMPLETED, content=result)

    return Tool(
        name=name,
        description=description,
        input_schema=input_schema,
        handler=handler,
        requires_approval=requires_approval,
    )

respond_to_invite

Python

respond_to_invite(*, description: str, name: str = 'respond_to_invite', locale: str = 'zh-CN', requires_approval: bool = True, as_user: bool = True, auth_scopes: Sequence[str] = ()) -> Tool

写类工厂：回复（RSVP）一个日程邀请——接受 / 待定 / 拒绝，返回一个需审批的 feishu.agent.tools.Tool。

处理函数解析日历（缺省取主日历），调用 client.calendar.events.reply(calendar_id, event_id, rsvp_status=...)。 requires_approval=True 时由 feishu.agent.loop.Agent 先发审批卡片，用户批准后才执行；回复的始终是请求 用户本人的日历邀请（按用户身份与主日历解析）。

示例：

>>> tool = respond_to_invite(description="回复日程邀请")
>>> tool.name, tool.requires_approval
('respond_to_invite', True)

源代码位于： feishu/agent/toolkit/calendar.py

def respond_to_invite(
    *,
    description: str,
    name: str = "respond_to_invite",
    locale: str = "zh-CN",
    requires_approval: bool = True,
    as_user: bool = True,
    auth_scopes: Sequence[str] = (),
) -> Tool:
    r"""
    写类工厂：回复（RSVP）一个日程邀请——接受 / 待定 / 拒绝，返回一个需审批的 [feishu.agent.tools.Tool][]。

    处理函数解析日历（缺省取主日历），调用 `client.calendar.events.reply(calendar_id, event_id, rsvp_status=...)`。
    `requires_approval=True` 时由 [feishu.agent.loop.Agent][] 先发审批卡片，用户批准后才执行；回复的始终是请求
    用户本人的日历邀请（按用户身份与主日历解析）。

    Examples:
        >>> tool = respond_to_invite(description="回复日程邀请")
        >>> tool.name, tool.requires_approval
        ('respond_to_invite', True)
    """
    input_schema: dict[str, Any] = {
        "type": "object",
        "properties": {
            "event_id": {"type": "string", "description": "event id to respond to"},
            "rsvp_status": {
                "type": "string",
                "enum": ["accept", "tentative", "decline"],
                "description": "RSVP response",
            },
            "calendar_id": {"type": "string", "description": "calendar id; defaults to the user's primary calendar"},
        },
        "required": ["event_id", "rsvp_status"],
        "additionalProperties": False,
    }

    async def handler(**arguments: Any) -> ToolResult:
        # Runs only AFTER the user approves the confirmation card; perform the write directly.
        client = await resolve_client(as_user=as_user)
        if client is None:
            return needs_user_auth(auth_scopes)
        calendar_id = await _resolve_calendar_id(client, arguments.get("calendar_id"))
        result = await client.calendar.events.reply(
            calendar_id, arguments["event_id"], rsvp_status=arguments["rsvp_status"]
        )
        return ToolResult(ToolOutcome.COMPLETED, content=result)

    return Tool(
        name=name,
        description=description,
        input_schema=input_schema,
        handler=handler,
        requires_approval=requires_approval,
    )