ExpAgent – Quick docs

ExpAgent runs automated participant agents (“jobs”) through online studies (e.g., oTree, Qualtrics) using LLMs.

Core objects

  • Experiment – a study container (platform type, description, members).
  • Session – run configuration (LLM credential + model + participant persona + optional LLM params).
  • Job – one participant agent. Jobs use a snapshot of the session settings at creation time and run independently.
  • Worker – background process that claims jobs from the database and progresses them.

Execution modes

  • HTTP plain (http_plain) – the agent advances by analyzing HTML pages and submitting HTTP form requests.
  • Headless browser (hl_browser) – the agent uses a browser runtime for interactive pages and JS-heavy flows.
  • The selected platform/mode is configured per session.

Typical workflow

  1. Create an Experiment.
  2. Create a Session, choose the platform mode, and select a LLM Credential plus an available Model.
  3. Edit the session participant persona (ROLE AND CONTEXT) if desired.
  4. Create Jobs (one URL or N copies of the same start URL).
  5. Workers run in the background; you can monitor progress on the session page.

LLM credentials and sharing

  • LLM credentials store provider, API URL, and API key (key is never shown again).
  • You can share credentials with specific other users if desired.
  • Each credential has a list of compatible models. Per-token pricing is tracked so you keep an overview over costs.

States and control

  • Jobs progress step by step using LLM interpretation, either via HTTP form submissions or browser actions (depending on session platform).
  • wait pages are polled in increasing time intervals; time intervalls reset after leaving a wait page.
  • Bulk and per-job actions: pause, resume, cancel.
  • Terminal states: completed, failed, cancelled. Some platforms (e.g. oTree) may also produce a terminal state “full” indicating that the (oTree) platform does not accept any more participants.

Logs and debugging

  • Open a job to see job events, checkpoints, and readable LLM logs (prompt + JSON response).
  • For hl_browser jobs, the job page also shows browser-specific status (session id, URL, proposed/validated actions, and recent visible text snippets).
  • Token and cost counters are updated incrementally as LLM calls happen.

Notes

  • Session edits affect only newly created jobs. Existing jobs keep their initial settings.
  • Use platform-appropriate start URLs (e.g., oTree InitializeParticipant links).
  • If a target study requires dynamic rendering or scripted interactions, prefer hl_browser over http_plain.