Sage

环境要求

• macOS(arm64/x86_64)、Windows(x86_64) 或 Linux(arm64/x86_64) 桌面系统
• Linux 桌面版需额外安装 GTK 与 bubblewrap
• 运行 Python 示例前需按官方文档完成 Python 环境准备（节选未包含该部分命令）
• 一个可用的模型服务凭证（供 MODEL_API_KEY 使用），调用可能产生费用

安装与启动步骤

1. 1下载桌面安装包

   从 GitHub Release 页面下载 Sage 2.0.0 对应平台安装包，按系统提示完成安装。

2. 2打开 Sage 配置模型

   启动 Sage，在 Settings → Configure an Agent 中添加模型，然后新建会话开始对话。

3. 3设置模型密钥

   把 MODEL_API_KEY 设置为你的模型服务密钥，示例代码会从环境变量读取该凭证。

   export MODEL_API_KEY="your-api-key"

   复制

4. 4创建 quickstart.py

   无需 sage.yaml，模型与服务信息以 YAML 文本内联在脚本里，把 your-model 换成可用模型名。

   """Set MODEL_API_KEY and replace your-model below; no sage.yaml file is needed."""
   
   import asyncio
   from uuid import uuid4
   
   from sagents.v2 import ActorRef, RequestContext, SAgentBuilder, StartRun
   from sagents.v2.contracts.commands import InputItem
   from sagents.v2.contracts.items import TextBlock
   from sagents.v2.contracts.principals import PrincipalType
   from sagents.v2.package.manifest import SageManifestLoader
   
   AGENT_YAML = """
   schema_version: sage/v2
   kind: application
   metadata: {id: example.assistant, version: 1.0.0, name: Assistant}
   credentials:
     api-key: {source: env, key: MODEL_API_KEY}
   models:
     primary:
       provider: openai-responses
       base_url: https://api.openai.com/v1
       credential: api-key
       model: your-model
   agents:
     main:
       name: Assistant
       instructions: {inline: "Be helpful and concise."}
       models: {primary: primary}
   entrypoint: {agent: main}
   """
   
   
   async def main():
       manifest = SageManifestLoader().loads(AGENT_YAML)
       app = await SAgentBuilder().with_defaults(session_root="runtime").build(manifest)
       try:
           context = RequestContext(actor=ActorRef(
               principal_id="user-1", principal_type=PrincipalType.USER,
           ))
           stream 

   复制

5. 5运行第一个智能体

   执行脚本后会打印事件流与最终状态；示例不含文件与 shell 工具，只用模型能力。

   python quickstart.py

   复制

关键配置

如何确认成功

终端逐行打印事件 JSON 并输出最终 state，即表示示例智能体运行成功。

常见问题

注意事项

• 桌面版已内置 Python 与后端，无需 clone 仓库、安装系统 Python 或 Flutter。
• macOS 包未公证、Windows 安装包未签名，首次打开可能触发安全拦截。
• quickstart 示例不包含文件与 shell 工具，只演示基础对话与事件流。
• 更完整的配置项可参考官方 GETTING_STARTED 与 DESKTOP 文档。