How agentuity/agent-hedgefund works
1. What this repo is
- This is a Python 3.10+ trading agent built for Agentuity and orchestrated with LangGraph.
- The system’s job is to turn a natural-language market/trading question into a concrete trading recommendation, with portfolio context, risk checks, and an action table.
2. Primary runtime and deployment boundary
- agentuity.yaml, main.py, and server.py are the deployment/serve boundary.
- The agent is meant to run locally via agentuity dev and in production on Agentuity’s hosted runtime.
- The repo also includes CI/deploy automation under .github/workflows/agentuity.yaml.
3. Top-level architecture
- The code is split into four clear layers:
- models/ for typed data contracts
- nodes/ for the LangGraph workflow steps
- services/ for domain logic and orchestration helpers
- tools/ for data acquisition and analysis utilities
- This separation is the main architectural boundary: workflow composition in nodes, business logic in services, external/algorithmic work in tools.
4. Workflow orchestration
- agents/hedge_fund/agent.py is the likely composition root that wires the graph together.
- The documented flow is: query parsing → asset search → technical analysis → risk assessment → portfolio decisions → response generation.
- nodes/workflow.py, nodes/routing.py, and the other node modules represent the graph stages and branching logic.
5. Input understanding and routing
- nodes/parsing.py plus tools/action_parser.py and the models in models/user_context.py and models/action.py handle interpretation of the user request.
- This layer extracts intent such as “buy”, “sell”, “hold”, position context, and risk signals before any market analysis happens.
- nodes/routing.py then decides which downstream path to take based on the parsed intent and complexity of the request.
6. Market asset discovery
- nodes/search.py and services/asset_search_service.py connect the request to a tradable asset or symbol.
- tools/asset_search.py is the lower-level lookup utility.
- This is the boundary where user language is normalized into concrete market instruments.
7. Technical analysis subsystem
- services/technical_analyst.py and tools/technical/ implement the quantitative market-analysis side.
- The technical toolset is split into:
- data_fetcher.py for pulling live price/market data
- indicators.py for indicator computation
- signal_interpreter.py for translating indicator values into directional signals
- manager.py for coordinating technical analysis
- The README indicates the main indicators are RSI, MACD, and EMA.
8. Sentiment and macro analysis subsystem
- services/market_sentiment_analyst.py and tools/sentiment/ provide non-price-based context.
- The sentiment tools are decomposed into news_analyzer.py, economic_analyzer.py, and fear_greed_analyzer.py, coordinated by tools/sentiment/manager.py.
- External data sources are environment-backed, including NewsAPI and FRED, which feed this layer.
9. Risk and portfolio decision engine
- nodes/risk_management.py, services/risk_manager_service.py, and services/trade_decision_service.py form the decision boundary.
- nodes/portfolio_manager.py and models/portfolio_decision.py represent the portfolio/action output.
- This layer combines analysis results with user holdings and risk constraints to produce concrete outcomes like BUY / SELL / HOLD, position sizing, and risk recommendations.
10. Response generation and formatting
- nodes/llm_response.py and services/response_formatter_service.py turn the internal decision into the final user-facing answer.
- The output is designed to be actionable, often including trade tables, entry/exit levels, stop losses, and sizing guidance.
- resources/ likely holds prompt or template assets used during this final formatting stage.
11. Data and type contracts
- The models in agents/hedge_fund/models/ define the structured data passed between layers:
- workflow.py for graph/state shape
- user_context.py for user and portfolio context
- action.py for parsed intent
- portfolio_decision.py for final recommendation data
- These contracts are important because the graph is stateful and each node passes structured state forward.
12. End-to-end data flow
- A request enters through the Agentuity-served endpoint, is parsed into structured intent, resolved to an asset, enriched with technical and sentiment data, checked against risk rules, converted into a portfolio decision, and finally formatted into a natural-language recommendation.
- The main external dependencies that materially shape the architecture are Agentuity for hosting/orchestration and live market/news APIs for data.
13. How to think about the system on a diagram
- Draw the system as a layered pipeline with a central LangGraph orchestrator.
- Put API ingestion at the top, then parsing/routing, then two parallel analysis branches (technical + sentiment), then risk/decision synthesis, then response formatting.
- Show external services only on the analysis side: market data, news, and macro/fear-greed inputs feeding into the analytical tools.
Main entry points: analysis.py Analysis · technical/manager.py Tech manager · sentiment/manager.py Sentiment manager · agent.py Agent root
Components 29
Runtime boundary
Agentuity entrypoints and deployment wiring
Workflow orchestration
LangGraph composition and state routing
- Agent root · Wires the hedge fund graph together
agents/hedge_fund/agent.py - Workflow state · Shared graph state passed between nodes
agents/hedge_fund/models/workflow.py - Parsing · Extracts intent and user context
agents/hedge_fund/nodes/parsing.py - Routing · Chooses the downstream path
agents/hedge_fund/nodes/routing.py - Search · Resolves user language to a tradable asset
agents/hedge_fund/nodes/search.py - Analysis · Runs market and sentiment analysis stages
agents/hedge_fund/nodes/analysis.py - Risk · Applies risk constraints and checks
agents/hedge_fund/nodes/risk_management.py - Portfolio · Converts analysis into a portfolio action
agents/hedge_fund/nodes/portfolio_manager.py - Response · Formats the final recommendation for the user
agents/hedge_fund/nodes/llm_response.py
Domain services
Business logic and decision helpers
- Controller · Coordinates the end-to-end agent flow
agents/hedge_fund/services/controller.py - Asset search · Maps requests to symbols and instruments
agents/hedge_fund/services/asset_search_service.py - Technical · Coordinates technical market analysis
agents/hedge_fund/services/technical_analyst.py - Sentiment · Coordinates news, macro, and fear-greed context
agents/hedge_fund/services/market_sentiment_analyst.py - Risk manager · Evaluates constraints and recommendation risk
agents/hedge_fund/services/risk_manager_service.py - Decision engine · Produces buy/sell/hold and sizing guidance
agents/hedge_fund/services/trade_decision_service.py - Formatter · Builds the final user-facing answer
agents/hedge_fund/services/response_formatter_service.py
Analysis tools
Market, sentiment, and technical analysis utilities
- Action parser · Normalizes intent from natural language
agents/hedge_fund/tools/action_parser.py - Asset lookup · Low-level tradable asset search
agents/hedge_fund/tools/asset_search.py - Tech manager · Runs the technical analysis pipeline
agents/hedge_fund/tools/technical/manager.py - Market data · Pulls live price and market data
agents/hedge_fund/tools/technical/data_fetcher.py - Indicators · Computes RSI, MACD, EMA and related signals
agents/hedge_fund/tools/technical/indicators.py - Signal interp · Converts indicator values into directional signals
agents/hedge_fund/tools/technical/signal_interpreter.py - Sentiment manager · Runs sentiment and macro sub-analyses
agents/hedge_fund/tools/sentiment/manager.py - News · Extracts sentiment from news sources
agents/hedge_fund/tools/sentiment/news_analyzer.py - Macro · Uses economic indicators and FRED-backed context
agents/hedge_fund/tools/sentiment/economic_analyzer.py - Fear greed · Reads market fear/greed sentiment
agents/hedge_fund/tools/sentiment/fear_greed_analyzer.py
Connections 30
- Agentuity → Main: deploys · Agentuity launches the application entrypoint
- Agentuity → Server: serves · Hosted runtime exposes the agent through the server boundary
- Main → Agent root: starts · Entrypoint initializes the hedge fund agent
- Server → Agent root: routes to · Server hands requests to the graph composition root
- Agent root → Workflow state: uses state · Graph operates over shared workflow state
- Agent root → Parsing: wires · Composition root connects the workflow stages
- Parsing → Action parser: parses with · User request is normalized into intent and context
- Parsing → Routing: outputs · Parsed state feeds routing decisions
- Routing → Search: may branch to · Requests needing symbol resolution go to search
- Routing → Analysis: may branch to · Resolved trades proceed to analysis
- Search → Asset search: uses · Search node delegates symbol resolution
- Asset search → Asset lookup: looks up · Service uses the lower-level asset lookup utility
- Analysis → Technical: runs · Technical analysis is coordinated here
- Analysis → Sentiment: runs · Sentiment and macro context are coordinated here
- Technical → Tech manager: coordinates · Service delegates to the technical toolchain
- Tech manager → Market data: fetches · Market data is retrieved first
- Tech manager → Indicators: computes · Indicator values are derived from data
- Tech manager → Signal interp: interprets · Signals are translated into actionable direction
- Sentiment → Sentiment manager: coordinates · Service delegates to sentiment tools
- Sentiment manager → News: analyzes · News sentiment is derived from headlines and articles
- Sentiment manager → Macro: analyzes · Macro context is derived from economic indicators
- Sentiment manager → Fear greed: analyzes · Fear/greed conditions are incorporated
- Analysis → Risk: feeds · Analysis results flow into risk checks
- Risk → Risk manager: checks with · Risk service evaluates constraints and exposure
- Risk → Portfolio: passes · Validated state continues to portfolio decisions
- Portfolio → Decision engine: decides with · Trade decision logic produces the recommendation
- Decision engine → Formatter: hands off to · Decision output is formatted for presentation
- Portfolio → Response: updates · Portfolio decision state feeds the response step
- Response → Formatter: formats with · Final response is rendered from structured decision data
- Formatter → Controller: returns via · Controller can assemble the final answer from services