Workflows

Select an agent architecture with --workflow on the CLI or workflow_type in Python. single_agent is the recommended first choice.

Workflow	Purpose	Requirements and constraints
single_agent	One general chemistry agent with local tools	Default; CLI and Python
main_agent	Direct workspace/chemistry work and configured specialists	Interactive CLI or MainAgentSession only
deep_agent	Workspace tasks and attached chemistry tools	CLI and Python; alias deepagent; broad local shell access
multi_agent	Routes tasks among specialized agents	More model calls and orchestration overhead
graspa	H2O, CO2, or N2 adsorption	Single-component runs; configured SYCL executable; alias graspa_agent
mock_agent	Deterministic development/testing route	Not intended for scientific work
graspa_mcp	gRASPA through MCP	Site and MCP setup required
rag_agent	Retrieval-augmented questions over documents	Install chemgraph[rag]
single_agent_xanes	XANES-focused single agent	Install chemgraph[xanes]; FDMNES and/or Materials Project access
molecular_docking	Protein-ligand docking workflow	Install chemgraph[docking]; Vina setup

Single agent

Start here for structure building, property lookup, ASE calculations, analysis, and reports:

chemgraph run --workflow single_agent \
  -q "Optimize water with EMT and report its final energy."

It minimizes orchestration complexity while exposing the normal tool set.

Main agent

main_agent uses the existing DeepAgent factory and works directly with skills, workspace files, shell commands, and lazy local tools. It may delegate substantial work to configured specialists while retaining one durable conversation:

chemgraph run --interactive --workflow main_agent --workspace . \
  --skill ../shared-skills --subagent single_agent --subagent deep_agent

By default the non-test built-in specialists are discoverable as metadata; none is active. search_agents finds workers and load_agents activates them before task delegation. A selection restricts the catalog; aliases resolve to canonical names and duplicates are rejected. Loaded workers last for one turn, including approval pauses, retry, and restart, and clear when it completes. An empty Python or TOML catalog disables discovery and delegation. deep_agent inherits the main workspace and skills. The legacy --deepagent worker keeps its separate --deepagent-* options and cannot also be selected through --subagent deep_agent.

Without --workspace, main-agent files live in checkpoints and no shell is available. Bundled skills and the host tool registry remain available. Host registry tools are independent of the file backend; use absolute host artifact paths. Workspace shell commands are not sandboxed to the selected directory. File mutations, shell commands, and reviewed registry operations pause for approval. Registry workers retain their own configured tools and private tool/skill state. They inherit mandatory parent reviews and may add stricter reviews.

Use --tool NAME to restrict the catalog and --no-discover-skills to disable automatic personal/project skill discovery. Selection survives model and workflow changes. Workspace and explicit skill paths are canonicalized on activation. Python supports these capabilities through ChemGraph and MainAgentSession; ChemGraph.run() rejects this workflow.

New graph sessions use schema version 4. Old transcripts remain readable, but old checkpoints require a new session. New supported CLI configurations restore through --resume or /resume; caller-owned Python configurations must be reconstructed through Python. See Python API.

Deep Agent

deep_agent is a reusable workflow with two entry points. It can run directly through ChemGraph(workflow_type="deep_agent"), or it can be discovered under main_agent as the deep_agent worker. The legacy --deepagent flag activates that worker with its separate options. Both paths use construct_deep_agent_graph, so the prompt, backend, tools, recursion limit, and approval policy have one implementation. Both entry points use DEFAULT_DEEPAGENT_PROMPT unless a custom prompt is supplied. The prompt permits attached chemistry tools; available tools are configured by the caller. The legacy main-agent workspace adapter is created without attached chemistry tools.

# Direct, process-local interactive thread with action reviews.
chemgraph run --interactive --workflow deep_agent --deepagent-workspace .

# The same worker delegated by the durable supervisor.
chemgraph run --interactive --workflow main_agent --deepagent \
  --deepagent-workspace . \
  --deepagent-skill ../external/AtomisticSkills/.agents/skills/

The standalone interactive workflow keeps one thread while that CLI process is open; it does not provide cross-process restoration in this first version. File mutations and shell commands require structured approve/reject decisions. In both CLI entry points, Enter approves the displayed action, n rejects it, and typed instructions skip that action and give the agent feedback for a revision. Other actions in the batch keep their individual decisions. See the CLI action reviews for shortcuts and previews. Headless execution is rejected unless both an explicit workspace and --deepagent-dangerously-skip-approvals are supplied.

Bundled skills and local personal/project skills load automatically. Repeat --deepagent-skill to add explicit sources with higher priority. Use --no-deepagent-discover-skills to disable local discovery. Python provides skills= / discover_skills= on construct_deep_agent_graph and deepagent_skills= / deepagent_discover_skills= on the higher-level APIs. Metadata refreshes before each new turn. See skills.

With the CLI's virtual local backend, /workspace is the project root exposed to the Deep Agent. For example, --deepagent-workspace test/ maps /workspace/script.py to test/script.py on the host. Deep Agents also tells the model the corresponding absolute host path to use with shell commands. Older files created under test/workspace/ are not moved automatically.

Run state and session records remain standard ChemGraph artifacts. By default, state snapshots are written under the process's cg_logs/session_* directory and session messages go to the configured ChemGraph session store; neither is placed inside the selected Deep Agent workspace. Approval-interrupted direct runs save both the pending checkpoint and the completed state after resumption.

Host shell access

The local backend can modify files under its workspace and its shell is not confined to that directory. Use only trusted prompts and disposable, isolated workspaces. The skip-approvals flag removes the action-review boundary for that run.

For comparisons with Claude Code or native Codex, keep the task set, starting checkout, time budget, and scoring fixed, and record which runtime performed each run. Selecting a codex: model here evaluates that model through ChemGraph's Deep Agent harness; it does not reproduce the native Codex product runtime. deep_agent is intentionally not included in the chemistry-focused chemgraph eval workflow matrix.

Multi-agent

multi_agent delegates among specialized graphs. It is useful when a request crosses distinct chemistry capabilities, but consumes more model tokens and may take more graph steps than single_agent.

Migrating from Python REPL

The python_relp workflow, its python_repl alias, and the python_repl tool have been removed. Use deep_agent for Python scripts and workspace tasks:

chemgraph run --interactive --workflow deep_agent --deepagent-workspace .

For the Python API, select workflow_type="deep_agent" and supply a deepagents.backends.LocalShellBackend through deepagent_backend when shell execution is needed. The default state backend has no shell. Execution and file changes retain DeepAgent's approval policy.

Update old workflow names in configurations and start a new DeepAgent session; legacy REPL sessions are not automatically converted. single_agent remains the default workflow.

Specialized workflows

RAG accepts supported text/PDF sources and may use provider embeddings or a local fallback. XANES, docking, gRASPA, and MCP workflows need the corresponding scientific engine, credentials, site configuration, or server. Consult Installation, Calculators, and MCP servers before selecting them.

Interface compatibility

The Streamlit interface exposes a subset of workflows. The CLI is the broadest discovery surface, but main_agent is interactive-only, deep_agent has an explicit local-access safety boundary, and some specialized workflows depend on local resources. Run chemgraph --help and chemgraph models against the installed release instead of assuming every workflow is available in every environment.