DojoAgents: A Portfolio-Aware Agent Loop for Retail Investors
DojoAgents: Full-Market AI Copilot for Personal Investment
At a glance
- What is it?
- DojoAgents is an Apache-2.0 Python framework that puts a reasoning agent next to your holdings, with a React dashboard and a CLI. It is a heavy stack, and its value depends on the LLM key you bring.
- Who is it for?
- Adopt DojoAgents if you already hold positions across A-shares, US and HK markets and want the reasoning trace exposed rather than a black-box signal. Skip it if you want a hosted product with no Python environment, or if you have no LLM API key to supply.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap DojoAgents targets: holdings-aware reasoning, not stock summaries
Most financial AI tools answer one question at a time. You paste a ticker, you get a summary. DojoAgents is built around the opposite assumption: that the useful unit of analysis is the portfolio, not the security. The README frames the distinction directly, saying most financial AI tools are built for quick outputs such as news summaries and single-stock explanations, while its Loop-Driven Cognitive Portfolio Agent is built for portfolio-aware reasoning.
The audience is the individual investor who already spreads positions across more than one market. The README's own example is a screenshot with 40+ positions spanning A-shares, US stocks and ETFs, which the agent re-groups by market, sector and supply-chain position before flagging over-concentration and overlapping exposure. That is a specific problem: forty tickers that are really three bets. A single-stock explainer cannot see that. A portfolio-level agent can, provided it can read the holdings in the first place.
The second audience is the investor who wants to see the work. The README states that during a run you can expand any intermediate step to see which tools were invoked, what data was cited, and how the analysis progressed. That trace is the product as much as the answer is.
Inside the Agent Loop: tool calls, four analysis dimensions, seven layers
The mechanism is a loop, not a pipeline. The README describes the agent entering a data-gathering phase and calling global market, sector and equity tools to pull movers, strength rankings, price changes, volume shifts and sector distribution across A-shares, US equities and HK stocks. The agent decides which tools to call, reads the results, and decides again. That is why the README calls it an Agent Loop engine rather than a dashboard.
The reasoning is organized into four stated dimensions: fundamental data cognition, advanced logic analysis, cross-market strategy deduction, and dynamic portfolio management. The third is the one worth testing. The README's example is the agent autonomously reasoning through why US semiconductor software dropped while A-shares surged, via multi-step tool execution. That is a linkage question, and linkage questions are where a loop either pays off or produces confident nonsense.
Architecturally, the README shows a seven-layer diagram running from CLI, Web Dashboard and Chat Gateways down through the Agent Loop to tools, data and infrastructure. The Python package confirms the shape: FastAPI and uvicorn for the server, apscheduler for scheduled work, pandas and pyarrow for the data layer, and strands-agents for the agent runtime. The dashboard is a separate React SPA, excluded from the Python package find directive and shipped as prebuilt assets under dojoagents.dashboard. Two runtimes, one repository.
Installing DojoAgents with uv and running a first portfolio question
The README recommends uv for dependency management and lists three requirements: Python >= 3.11, Node.js >= 18 for the frontend build, and an LLM API key from OpenAI, Gemini, Anthropic or similar. The pyproject file agrees on the Python floor with requires-python = ">=3.11".
The README's Quick Start installs the package from PyPI under the name dojoagents. A console script is registered in pyproject as dojoagents, pointing at dojoagents.cli.main:main, so the CLI is the entry point once installation finishes.
uv pip install dojoagents
dojoagents --helpIf you prefer pip, the same distribution works, though the README's stated preference is uv. The runtime dependency set is not small: openai, fastapi, uvicorn, httpx, pandas, pyarrow, apscheduler, mcp, strands-agents, dojosdk and exchange-calendars all land in the environment. Expect a slow first resolve.
The dashboard is a separate build. Because the Python package excludes dojoagents.dashboard.web, the frontend is shipped as prebuilt assets in the wheel, so you do not normally need Node unless you are building the SPA yourself. Node >= 18 and npm >= 9 are listed as requirements for that case.
For a first real use, the README's own walkthroughs are the honest starting point: ask for a daily market overview, or upload a holdings screenshot and read the diagnosis. The screenshot path requires a multimodal model, since the agent has to read positions off an image rather than a CSV. The README does not document a rollback or undo for a generated watchlist portfolio, so treat the simulated portfolio as a sandbox rather than a ledger.
Where DojoAgents breaks down: install docs, LLM dependency, market coverage
The README is truncated mid-install. The section headed Core Install stops before showing the command, and the Quick Start never reaches a configuration step. There is no documented example of where the LLM API key is placed, no config file path, and no environment variable name anywhere in the README. For a project whose entire function depends on a model provider, that is the largest documentation gap, and it means the first hour is guesswork unless the repository's docs directory fills it in.
Second, the loop is only as good as the model behind it. Every dimension in the four-part framework is an LLM reasoning step. A weaker or cheaper model does not degrade gracefully here; it produces cross-market linkages that sound plausible and are wrong. The README does not describe any validation layer, confidence scoring or grounding check between a tool result and a stated conclusion.
Third, coverage is declared, not proven. The README names A-shares, US equities and HK stocks, and the dependency list includes exchange-calendars, which suggests trading-session awareness. But the README does not list which data vendors sit behind the market, sector and equity tools, nor their rate limits, licensing or latency. If your strategy depends on intraday data, nothing here tells you whether you will get it.
Finally, this is the wrong tool if you want a hosted service. There is no homepage, no managed endpoint mentioned, and no release artifacts retrieved. You run the server yourself.
DojoAgents versus a general agent framework such as strands-agents
The most informative comparison is not with another finance app. It is with the agent runtime DojoAgents itself depends on. The pyproject lists strands-agents and strands-agents-tools as dependencies, which means the generic agent loop is already in the environment before DojoAgents adds anything.
The difference is domain packaging. A bare strands-agents setup gives you a loop and a tool registry; you would still write the market data connectors, the sector taxonomy, the portfolio model, the risk diagnosis prompts and the dashboard. DojoAgents ships those as built-in assets. The pyproject package-data section is the evidence: skills/built_in, harnesses/built_in/financial/tasks/definitions, harnesses/built_in/financial/pipelines/definitions and dashboard/data/default_portfolios are all bundled into the wheel. That is the actual product, and it is why installing DojoAgents pulls a much larger tree than installing its runtime.
The trade-off runs the other way too. If your market is not A-shares, US or HK, the built-in financial harness is the wrong shape and you are paying the dependency cost for assets you will not use. At that point a bare strands-agents install plus your own tools is the smaller system.
Licence, versioning and what an upgrade actually costs
DojoAgents is Apache-2.0, which permits commercial use, modification and redistribution provided you preserve the licence and notice files and state significant changes. That is a permissive position, but it says nothing about the data flowing through the agent. Market data, news feeds and screenshot contents carry their own terms, and the README does not name the underlying providers, so the licence question you need to answer is not the repository's.
Versioning is at 0.2.4 in pyproject, with no releases retrieved. A 0.x version number is a signal about API stability, not a guarantee, and the absence of published releases means there is no changelog to diff between versions. Upgrading means reading commits.
The dependency bounds are the real upgrade cost. Several are pinned to a single minor line: fastapi is constrained to >=0.115.2,<0.116, and uvicorn appears as >=0.31.1,<0.36.0 in pyproject but >=0.31.1,<0.33.0 in requirements.txt. Those two files disagree. If you install from requirements.txt you get a narrower uvicorn range than the package metadata declares, and a future FastAPI minor release will require a coordinated bump across both files plus whatever strands-agents expects. Budget for that before you build anything on top.
Editorial conclusion
Adopt DojoAgents if you already hold positions across A-shares, US and HK markets and want the reasoning trace exposed rather than a black-box signal. Skip it if you want a hosted product with no Python environment, or if you have no LLM API key to supply. Before committing, read the rest of the Quick Start section on GitHub, since the README ends mid-install, and confirm that the dojosdk dependency resolves against your Python version.
Frequently asked questions
How do I define an AI agent?
The DojoAgents README does not give a general definition. It describes its own engine as an Agent Loop that enters a data-gathering phase, calls market, sector and equity tools, and lets you expand intermediate steps to see which tools were invoked and what data was cited.
What Python version does DojoAgents require?
The README lists Python >= 3.11 as a requirement, and pyproject.toml sets requires-python = ">=3.11". Node.js >= 18 and npm >= 9 are listed for the frontend build.
What licence does DojoAgents use?
The repository is licensed under Apache-2.0. That covers the code; the README does not name the market data or news providers behind the agent's tools, so their terms are separate.
Community notes