assistant - PythonIDE Docs

端侧助手（Foundation Models + 内置设备工具，iOS 26+）：自然语言任务、可选工具调用。

边界：设备端推理，内置工具由系统提供（见 list_tools()）。不含 PythonIDE 云端 Agent；复杂多步自动化请用应用内 Agent 功能。

#模块概览

项	说明
导入	`import assistant`
适合做什么	「帮我查天气」「总结这段文字」等带工具的自然语言任务
调用时机	`run()` 放在按钮回调；可能较慢
推荐顺序	`is_available()` → `list_tools()` → `run(prompt, tools=...)`
返回	`{"text": str, "tool_calls": list}`

#快速开始

python

import assistant

if not assistant.is_available():
    print("Assistant 不可用")
else:
    print("内置工具:", assistant.list_tools())
    result = assistant.run("用一句话介绍今天的日期")
    print(result["text"])
    print(result.get("tool_calls", []))

指定工具子集：

python

import assistant

result = assistant.run(
    "查询当前位置附近的天气",
    tools=["location", "weather"],
)
print(result)

#AppUI 示例

python

import appui
import assistant

state = appui.State(
    available="—",
    tools="—",
    prompt="今天适合出门跑步吗？",
    reply="—",
)


def refresh_meta():
    state.available = "是" if assistant.is_available() else "否"
    names = assistant.list_tools() or []
    state.tools = str(len(names)) + " 个内置工具"


def run_task():
    refresh_meta()
    if state.available != "是":
        state.reply = "Assistant 不可用（需 iOS 26+）"
        return

    try:
        result = assistant.run(state.prompt)
        calls = result.get("tool_calls", [])
        suffix = f"（调用 {len(calls)} 个工具）" if calls else ""
        state.reply = (result.get("text") or "—") + suffix
    except assistant.AssistantError as exc:
        state.reply = str(exc)


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("任务", [
                appui.TextEditor(text=state.prompt).frame(min_height=80),
                appui.Button("运行助手", action=run_task)
                .button_style("bordered_prominent"),
            ]),
            appui.Section("状态", [
                appui.LabeledContent("可用", value=state.available),
                appui.LabeledContent("工具", value=state.tools),
                appui.Text(state.reply).foreground_color("secondaryLabel"),
            ]),
        ]).navigation_title("端侧助手")
    )


appui.run(body, state=state)

#API 参考

#速查

API	作用
`is_available()`	助手是否可用 → `bool`
`list_tools()`	内置工具描述列表
`run(prompt, tools=None)`	执行任务 → `dict`
`AssistantError`	操作失败异常

#run

run(prompt, tools=None) — 发送自然语言任务。

字段	说明
`text`	助手最终文本回复
`tool_calls`	工具调用记录列表

python

result = assistant.run("总结这段话", tools=None)
print(result["text"])

tools 为工具名字符串列表时，限制可用内置工具范围。

#常见错误

错误写法	后果	修正
与 `foundation_models` 混用场景	能力重叠	纯文本用 `foundation_models`；要工具用 `assistant`
在 `body()` 里 `run`	每次刷新重复推理	放进按钮回调
低版本 iOS	`is_available()` 为 False	降级为规则逻辑或提示用户
期望执行任意 Python 代码	超出能力	工具仅限系统内置集合

#相关文档

文档	用途
foundation_models	纯文本生成/摘要
weather	直接调用天气 API
location	直接调用定位 API

#预期效果

运行示例后，界面应出现文档描述的目标结果；若与预期不符，先看「失败路径」并按返回值或日志排查。