Photo Agents
A local Python runtime for screen-aware LLM automation with layered memory and tool execution.
What does this agent do, and when should you use it?
Photo Agents is a locally run Python package for photo-aware agents that operate a computer through a perceive, reason, and act loop. Its runtime combines a streaming agent loop, multi-provider LLM routing, file I/O, sandboxed code execution, browser automation, and layered memory. It documents native paths for Anthropic Claude and OpenAI GPT, plus a mixin failover session. The repository offers a terminal REPL, one-shot task execution, reflect/watchdog mode, and Streamlit, PyQt, and chat-platform clients. A remotely validated Photo Agents API key is required, while memory, skills, and session archives are kept in local directories.
When started with python -m photoagents, the core agent loop drives a tool-calling LLM through a perceive → reason → act cycle. It can perform file I/O, run sandboxed Python, PowerShell, or bash code, and automate a browser through a Chrome DevTools Protocol bridge. The runtime stores working memory, global memory, SOPs, and session archives in layers, and keeps a skill/SOP search vector index under ~/.photoagents/skill_index/. photoagents/evolution/scheduler.py supports reflect/watchdog mode, where a check() function triggers the next task; Langfuse observability and cron-style scheduling are optional components.
- A developer who wants a tool-calling LLM to identify the largest files in the current directory can run a one-shot file-I/O task.
- A user automating work from visible browser state can use the Chrome DevTools Protocol bridge-based browser tooling.
- An individual who needs persistent facts, SOPs, and raw session histories for recurring automation can use the local layered memory under `~/.photoagents/`.
- A team choosing between terminal, Streamlit web, and PyQt desktop interaction can launch the matching client.
- An automation maintainer who wants follow-on tasks triggered by a `check()` condition can use reflect/watchdog mode.
What are this agent's strengths and limitations?
- Combines a streaming agent loop, file operations, code execution, browser automation, and layered memory in one Python runtime.
- Documents native support for Anthropic Claude and OpenAI GPT, with a mixin failover session.
- Keeps memory, session archives, and skill indexing locally under `~/.photoagents/`, which supports persistent local state.
- Provides terminal, web, desktop, and several chat-platform client options rather than one interaction surface.
- Every service launch depends on a remotely validated Photo Agents API key; a missing or revoked key prevents startup.
- The agent loop requires a network-reachable LLM provider, so it cannot run fully offline.
- Browser tooling depends on `beautifulsoup4` and CDP bridge configuration under `resources/tmwd_cdp_bridge/`.
- The project is beta, and its APIs may change before version 1.0.
How do you install or deploy this agent?
Python 3.10 or newer is required. Install with pip install photoagents; for all optional clients and integrations, use pip install "photoagents[all]". Set PHOTOAGENTS_API_KEY=pk_live_..., or save the key as api_key in ~/.photoagents/config.json; the first run can also prompt interactively. From the repository root, run cp photoagents/config/keys_template.py credentials.py, then edit credentials.py and enable one provider configuration. A credentials.json file with the same shape is also accepted.
How do you use this agent?
Configure the API key and LLM credentials first. Start the interactive terminal REPL with python -m photoagents. Run a single task with python -m photoagents --task my_task --input "List the largest files in this directory.". Start reflect/watchdog mode with python -m photoagents --reflect photoagents/evolution/scheduler.py. Optional clients include python -m photoagents.clients.desktop_app and pythonw -m photoagents.cli.launcher.