Photo Agents
让 LLM 基于屏幕观察、分层记忆和工具调用执行本机任务。
这个 Agent 能做什么，适合哪些场景？
Photo Agents 是一个本地运行的 Python 包，用于构建通过感知、推理、行动循环操作计算机的照片感知型代理。其核心包含流式 agent loop、LLM 多提供商路由、文件 I/O、沙盒代码执行、浏览器自动化和分层记忆。运行时支持 Anthropic Claude 与 OpenAI GPT 的原生接入，也提供 mixin 故障切换会话。项目提供终端 REPL、单次任务命令、反思/看门狗模式，以及 Streamlit、PyQt 和多种聊天平台客户端。它要求远程验证的 Photo Agents API 密钥，记忆、技能和会话归档保存在本机目录中。
运行 python -m photoagents 时，核心 agent loop 驱动支持工具调用的 LLM，按 perceive → reason → act 循环执行任务。它可进行文件 I/O，并在 Python、PowerShell 或 bash 中执行沙盒代码；浏览器操作通过 Chrome DevTools Protocol bridge 进行。系统将工作记忆、全局记忆、SOP 和会话归档分层保存，并在 ~/.photoagents/skill_index/ 中维护技能/SOP 搜索向量索引。photoagents/evolution/scheduler.py 可用于 reflect/watchdog 模式，由 check() 函数触发下一项任务；可选 Langfuse 集成和 cron 风格调度也在项目范围内。
- 需要在本机终端中让工具调用型 LLM 分析当前目录最大文件的开发者，可用单次 file-I/O 模式执行任务。
- 希望让代理根据浏览器页面状态完成操作的用户，可使用 Chrome DevTools Protocol bridge 的浏览器自动化能力。
- 需要长期保留事实、SOP 与原始会话记录的个人自动化使用者，可采用 `~/.photoagents/` 下的分层本地记忆。
- 希望在终端、Streamlit 网页端或 PyQt 桌面端之间选择操作界面的团队，可部署对应客户端。
- 需要由 `check()` 条件持续触发后续任务的自动化维护者，可运行 reflect/watchdog 模式。
这个 Agent 有哪些优点和局限？
- 将流式 agent loop、文件操作、代码执行、浏览器自动化和分层记忆集中在一个 Python 运行时中。
- 原生支持 Anthropic Claude 与 OpenAI GPT，并提供 mixin 故障切换会话。
- 记忆、会话归档和技能索引存放于本地 `~/.photoagents/`，适合需要本地状态持久化的场景。
- 提供终端、网页、桌面和多个聊天平台客户端，而非只提供单一交互入口。
- 启动任何服务都依赖远程验证的 Photo Agents API key；密钥缺失或被撤销时启动会被拒绝。
- agent loop 需要可联网的 LLM 提供商，因此不能完全离线运行。
- 浏览器工具依赖 `beautifulsoup4` 以及 `resources/tmwd_cdp_bridge/` 下的 CDP bridge 配置。
- 项目状态为 beta，文档明确说明 1.0 前 API 可能变化。
如何安装或部署这个 Agent？
需要 Python 3.10 或更高版本。安装：pip install photoagents；如需全部可选客户端和集成：pip install "photoagents[all]"。配置 PHOTOAGENTS_API_KEY=pk_live_...，或将 API key 保存到 ~/.photoagents/config.json 的 api_key 字段；首次运行也会交互式提示。然后在仓库根目录执行 cp photoagents/config/keys_template.py credentials.py，编辑 credentials.py 并启用一个提供商配置；也可使用同结构的 credentials.json。
如何使用这个 Agent？
先完成 API key 与 LLM 凭据配置。启动交互式终端：python -m photoagents。执行一次任务：python -m photoagents --task my_task --input "List the largest files in this directory."。启动反思/看门狗模式：python -m photoagents --reflect photoagents/evolution/scheduler.py。可选前端包括 python -m photoagents.clients.desktop_app，以及 pythonw -m photoagents.cli.launcher。