StockAgent: multi-agent LLM simulation of stock trading behaviour

A simulator for trader behaviour, not a prediction model

StockAgent asks a research question rather than shipping a trading strategy. The framing in the README is whether AI agents can simulate real world trading environments to investigate the impact of external factors on trading activity, with the examples given being macroeconomics, policy changes, company fundamentals and global events. The claim is that these factors influence trading behaviours and matter for the profits of investors.

The system is a multi-agent AI system driven by large language models, designed to simulate investors' trading behaviours in response to the real stock market. The point is evaluation: it lets a user assess how different external factors change trading and profitability effects, and it records the behaviour so it can be analysed.

The most interesting technical claim is the one about leakage. Existing trading simulation systems based on AI agents are said to have a test set leakage problem, and StockAgent's answer is to prevent the model from exploiting prior knowledge it may have acquired about the test data. That matters more than it might sound. A model that has seen the period it is being asked to simulate will produce behaviour that looks like insight and is actually recall, and any conclusion drawn from such a simulation would be worthless. A simulation framework built around a large language model inherits that risk by construction, which is why the project makes a point of it.

The work is published: an arXiv link, 2407.18957, and acceptance by ACM Transactions on Intelligent Systems and Technology, and the README asks users to cite the paper if the code proves valuable.

Four phases, and events that arrive on their own schedule

The simulation loop has four phases, and the README describes each of them. The Initial Phase sets up the run, the Trading Phase is the main activity, the Post-Trading Phase handles the aftermath, and the Special Events Phase covers something that happens unexpectedly.

The interesting detail is the frequency model inside the Post-Trading Phase. Daily events occur with daily frequency and quarterly events with quarterly frequency, which is how the simulation injects routine information into the agents' environment on a schedule that matches how such information actually arrives in a market. A daily event is something the market learns each session, and a quarterly event is the earnings style disclosure that lands four times a year.

The Special Events Phase is different in kind. The README describes it as an event that occurs randomly and acts on a random trading day, so it is the mechanism for global events, the sort of thing with no schedule. The four way split matters because it separates the recurring environment from the exceptional one, and it lets a study attribute a change in behaviour to one class of shock rather than to noise.

The repository layout supports the same division. There is agent.py for the agent behaviour, stock.py for the market side, secretary.py for the figure, and record.py for logging, with a prompt directory holding the prompts that drive the agents and a log directory for the run output. The figures directory holds the workflow and schematic images the README shows.

Setting up: conda, PromptCoder and two API keys

The environment setup is a fixed sequence, and it involves a second project you have to install first. The first half of it, creating the conda environment and installing the helper project in editable mode, looks like this:

conda create --name stockagent python=3.9
conda activate stockagent

git clone https://github.com/dhh1995/PromptCoder
cd PromptCoder
pip install -e .
cd ..

PromptCoder is a separate repository that has to be cloned and installed before the simulation code, and the README refers to it as the tool used here. The second half of the sequence is to clone this repository, move into its directory and install the pinned requirements with pip install -r requirements.txt. The README writes the clone step for this repository in generic terms rather than with a URL, which is a small sign of a research codebase rather than a packaged distribution.

The agent needs a model provider, and the README gives one environment variable per option, OPENAI_API_KEY for the GPT models and GOOGLE_API_KEY for Gemini. Both are exported into the shell before the run, and nothing else needs to be configured for the model call.

The dependency list is pinned exactly, and it is short: colorama 0.4.4, openai 1.13.3, pandas 1.3.5, protobuf 3.20.3, Requests 2.31.0 and tiktoken 0.5.1. Two of those pins date the project. pandas 1.3.5 and the Python 3.9 environment in the setup block place this on an older stack than a current team would choose, and the openai client at 1.13.3 predates most of the API surface that has been added since, so plan for a dependency refresh before running anything at scale.

Running a simulation is one command and one model name

The start step is a single command, python main.py, with a --model option naming the model to use. That option is the point. StockAgent evaluates different LLMs under the same framework, and the README states that gemini-pro is set as the default LLM, so running with no flag still does something.

That framing is what makes the project a research instrument rather than a demo. The same market, the same event schedule and the same prompts are run against different models, and the outputs are compared. The experimental results are described as demonstrating the impact of key external factors on stock market trading, including trading behaviour and stock price fluctuation rules, and the work is framed as exploring the study of agents' free trading gaps in the context of no prior knowledge related to market data.

The final line of the README's claim is the one to keep in mind. The patterns identified through simulations are offered as insights for LLM based investment advice and stock recommendation, which is a much stronger claim than the framework alone supports. A simulation can show how an agent behaves under a given event schedule; whether those patterns translate into advice for real money is a separate question the repository does not answer.

No licence, no releases, and a flat script layout

Two facts about the repository as a software artefact should be checked before anyone builds on it.

The first is the licence. The project metadata records no licence for the repository, and the README does not mention one either. That is not a permissive default: with no grant of rights, the default copyright position applies, so the code is not something you can legally copy, modify or redistribute without the author's permission. For a research codebase that is often overlooked, and it is the single most important thing to sort out before this code enters a company repository.

The second is the distribution story. There are no GitHub releases, and the last push to the repository was on 2026-06-16, so there is no version to pin to and no changelog to read beyond the paper.

The code layout is that of a research script rather than a package. The top level holds main.py, agent.py, stock.py, secretary.py, record.py and util.py as loose modules, with directories for the prompts, the log output and the figures. There is no package manifest, no entry point in a console script and no test directory in the listing. That is fine for reproducing a paper and awkward for anything else.

The prompts directory is worth a close look before you run anything, because in an LLM agent the prompt is the policy. The behaviour you are studying is the behaviour the prompts specify, and the README does not describe what the agents are told beyond the surrounding narrative.

Editorial conclusion

Adopt StockAgent if you are researching how external factors such as policy changes, company fundamentals or global events affect trader behaviour, and you want a multi-agent simulation rather than a prediction model. Do not adopt it as a trading system or as a source you intend to build on commercially, because the repository carries no licence terms at all, which means the default copyright position applies. Verify first that the simulator's data and prompts reflect your market, that the leakage prevention claim holds for the model you plan to point at it, since the whole design rests on the agent having no prior knowledge of the test period, and that the pinned dependency versions, including Python 3.9 and pandas 1.3.5, still install in your environment.

Frequently asked questions

Official sources

1. Issues
2. MingyuJ666/Stockagent on GitHub
3. README