CAS-Framework

Collaborative Agentic Search — a framework for running AI agents that collaborate on a campaign, submitting work to HPC systems, reasoning about the results, and coordinating with each other through a shared directory.

The framework is domain-agnostic. You supply the science and the compute:

• a task file saying what a job is
• prompts describing what is being searched and what makes a result good
• a Globus Compute endpoint on each HPC system you want to use

It supplies everything around that: the agent loop, job claiming so several agents never duplicate work, run tracking, clean shutdown, and optional chat integration.

A concrete instance is named CAS-<domain> — for example CAS-QA, Collaborative Agentic Search for Quantum Advantage, which this framework was extracted from.

What it gives you

• Agents that run continuously. Submitting work, collecting results, and deciding what to try next.
• A method, not just a loop. The agent works in explicit cycles — observe, hypothesise, predict, experiment, interpret — recording predictions before running, keeping a terse cross-run logbook, and writing each cycle up in a journal.
• Several researchers on one campaign. Each runs their own agents against the HPC systems they have access to, so a campaign can span machines and allocations that no single person holds. The agents coordinate through the shared directory and claim work before running it, so no two duplicate each other. There is no central controller.
• Operational control. See which agents are alive and where; stop one cleanly so it finishes its current work and writes it up before exiting.
• Slack Integration (optional). The agents post their own status, milestones and alerts as they go. You can also message the agent system: ask what the best result so far is, what a cycle concluded, or which agents are running, and get an answer in seconds — or send an instruction that redirects a running agent, pointing it at a different region or telling it to wind down.

Layout

cas_agent/          the framework. run from here
  agent.py          the round loop, run tracking, shutdown
  tools.py          job submission, claims, capacity, the MCP tools
  prompt.md         how the agent works (generic) + a DOMAIN section you edit
  user_prompt.md    the brief for one run
  config.json       your systems, endpoints, queues
  list_agents.sh    which agents are running
  kill_agent.sh     stop one cleanly
example/            a worked example: a toy MPI job you can actually run
endpoints/          working Globus Compute endpoint templates (PBS, Slurm)
shared/             the shared directory the agents coordinate through
docs/               setup and optional extras

Quick start

pip install -r requirements.txt

1. Start a Globus Compute endpoint on your compute system and note its UUID. Templates for PBS and Slurm: endpoints/.
2. Put the UUID and your queue details in cas_agent/config.json.
3. Write your task — one file. Copy example/ and edit.
4. Describe your domain in the DOMAIN section of cas_agent/prompt.md, and the run's goal in cas_agent/user_prompt.md.
5. Edit and run cas_agent/run_example.sh, inside tmux.

Full walkthrough: docs/setup.md.

Running it

./list_agents.sh                     # agents running now
./list_agents.sh --all               # every run, and how it ended
./kill_agent.sh --drain <run_id>     # finish current work, write up, exit

--drain is the normal way to stop an agent: it stops submitting, collects what is already running, writes up the cycle, then exits. It sends no signal, so it works from any machine that can see the shared directory.

Writing a task

One file with four things — a description the agent reads, an argument schema, a key identifying a piece of work, and a function that runs on the cluster:

JOB_DESC   = "Run the simulation. Pass size (grid points, 64-4096) ..."
JOB_SCHEMA = {"size": int, "seed": int}

def job_key(args):
    return f"size={args['size']},seed={args.get('seed', 0)}"

def remote_fn(args, target):
    import subprocess               # imports go INSIDE: see the docs
    ...
    return {"energy": ..., "seconds": ...}

Optionally a cheap local comparator, which the framework offers to the agent only if you define one.

remote_fn is shipped to the worker by source, so it cannot see the rest of your module. Every import goes inside it, and paths come in through target. Details and a checklist: docs/writing_a_task.md.

Optional extras

• docs/slack.md — status messages; two-way chat with a running agent.
• docs/globus_transfer.md — sync the shared directory between machines.

Neither is required. Without them the agent runs exactly the same, quietly.

Requirements

Python 3.10+, the claude CLI, and a Globus Compute endpoint on whatever machine runs the work.