ESG Portfolio Agent

Portfolio carbon analysis and pre-trade ESG compliance, built on an existing enterprise system

Claude tool use MCP FastAPI Docker Compose Reference architecture

A portfolio manager asks a question in plain language. A language model chooses each next step; deterministic services retrieve definitions, compute every number, and check trades against the fund's ESG mandate. The model never calculates a figure and never executes an action itself, and a trade that breaches the mandate waits for a second person to approve.

The problem

Asset managers report their funds' carbon footprint under TCFD and SFDR. Answering even a simple question, such as how carbon-intensive a portfolio is and which holdings drive it, means finding the right metric, computing it company by company, handling missing data, and aggregating the result. Checking whether a proposed trade still fits the fund's ESG mandate adds a compliance step on top.

An LLM can drive this conversation, but it should not be trusted to calculate figures or to approve trades. This project shows how to give the model the planning role while existing enterprise services keep authority over data, computation, and consequential actions.

"What is the carbon intensity of my portfolio in 2023, and which holdings drive it?"
"Buy 5 points more NXP, funded from Infineon. Does it comply with the mandate? If so, submit it."

What I built

Model-driven tool-use loop

Claude chooses the next capability through strict tool definitions. An output contract rejects refusals and truncated responses, and a hard cap bounds model calls per request.

Three MCP servers

The existing ESG knowledge graph, the metric computation service, and a new portfolio and compliance service are exposed over the Model Context Protocol, so the agent integrates the existing system instead of reimplementing it.

Enterprise controls in code

Signed sessions, role-based entitlements, rate limits and egress checks at the boundary; authorization at every service call; a four-eyes gate that holds breaching trades until a compliance officer who is not the submitter approves.

Number check

Every figure in an answer must appear in the request or in a service result. Drafts that contain a model-derived number are returned once for revision; all 21 recorded answers passed.

Cost-aware inference

Prompt caching of tool definitions, system prompt and conversation prefix serves about 14k of 17k input tokens per question from cache; every model call reports its token usage on the trace.

Evaluation harness

Every exchange between components is recorded as a typed interaction. Scripts replay seven question types three times each and run probes that deliberately try to break the rules.

Architecture

The design follows a technology-neutral reference architecture for enterprise agentic AI with ten responsibilities (L0–L9). The agent realizes seven of them: the client page (L1), the access gate (L2), the agent runtime (L3), model access (L4), the knowledge graph (L5), the computation and compliance services (L6), and the container deployment (L8).

Reference architecture with ten responsibilities L0 to L9 and typed interactions T1 to T8
Reference architecture. Each box is a responsibility; arrows are typed interactions. Guardrails sit where the checked decision is owned, not in a separate layer.

A recorded run

A portfolio manager holds STMicroelectronics (30%), Infineon (25%), Micron (25%) and TSMC (20%) and asks for the 2023 carbon intensity. The agent looks up the metric definition in the knowledge graph, has the computation service calculate each holding, and has the portfolio service compute the weighted average carbon intensity (WACI). TSMC has no revenue data, so it is excluded and the gap is reported rather than estimated.

163.59
WACI, t CO₂e per USD m
84%
of it driven by Micron
27
recorded exchanges
0
numbers invented by the model
Sequence diagram of the recorded execution with 27 numbered messages
Every message between components, as recorded. Blue: requests; green dashed: results. The model (right) only decides the next step; the services return every number in the final answer.

Results across seven questions

Each question was run three times, because the model's choices are not deterministic.

QuestionExchangesService callsOutcome
Intensity and drivers, 4 holdings275Answered
Change since 202239–4110Answered
One holding without revenue data275Answered, gap reported
Intensity and drivers, 7 holdings358Answered
Trade within the mandate; submit31–336–7Cleared
Trade breaching the mandate; override337Held for approval
Share prices (not in the data)50Declined

Trying to break it

I wrote probes that would succeed only if a control were missing. None did.

ProbeResult
Request with a forged session tokenRefused at the boundary
User without the computation entitlement calls the serviceRefused by the service
Portfolio manager (no override right) approves a breaching tradeRefused
Submitter who also holds the override right approvesRefused (four-eyes rule)
Compliance officer approvesApproved
Reported figures compared with service resultsIdentical

Run it

# the agent sits on top of an existing ESG metric system git clone https://github.com/Inspiring-Ming/AI-Agent-for-ESG cd AI-Agent-for-ESG git clone https://github.com/Inspiring-Ming/ESG-Metric-System ../esg-system export ESG_REPO=../esg-system # path to the existing ESG system cp .env.example .env # add your ANTHROPIC_API_KEY docker compose up -d --build # ESG system, three MCP servers, agent service open http://localhost:8090 # ask questions, watch each step, approve overrides ./evaluate.sh # reproduce the recorded results