DEV Community: SupplyGraph.AI

Automating Supplier Due Diligence with AI: Turning Days of Work into Minutes

SupplyGraph.AI — Tue, 09 Dec 2025 02:36:30 +0000

Global supply chains are evolving faster than traditional due diligence workflows can support. Analysts must navigate fragmented public records, inconsistent disclosures, and region-specific data systems — all while responding to rising expectations across ESG, sanctions, corporate governance, labor compliance, cybersecurity, and financial transparency.

The result? Due diligence has become one of the most time-consuming and resource-intensive steps in supplier onboarding, M&A screening, and third-party risk management.

SupplyGraph AI’s Automated Due Diligence Agent was designed to address these challenges by transforming manual research into a structured, repeatable, and scalable intelligence process.

The Pain: Why Traditional Due Diligence Fails at Scale

Even for a single supplier, analysts often spend 10+ hours manually compiling information from numerous sources:

Corporate registration and identity records
Ownership and shareholder structures
Legal filings, regulatory actions, and sanctions
Intellectual property portfolios
Financial disclosures
Workforce, operations, and business scope
ESG-related or governance-related signals

The complexity increases as organizations expand across markets or face stricter compliance requirements.

Common issues include:

Slow and inconsistent information gathering
Outdated reports due to static snapshots
Limited visibility across jurisdictions
High operational cost
Fragmented data formats

These gaps introduce delays, blind spots, and elevated risk exposure.

The Breakthrough: Automated, Structured, and Continuously Refreshed Due Diligence

The Due Diligence Agent consolidates globally dispersed corporate information into a unified, structured, and evidence-linked intelligence report.

Behind the scenes, it:

Resolves company identity across global registries
Structures information into standardized due-diligence modules
Extracts legal, financial, IP, operational, and compliance-related signals
Benchmarks companies using more than 8,000 statistical industry matrices
Refreshes data on a rolling update cycle, ensuring reports incorporate the latest available information

From the user’s perspective, the process requires only:

Enter a company name
Confirm the matched entity
Receive a comprehensive (or chapter-specific) report in minutes

No custom integrations, no manual aggregation.

What the Report Contains

Each report follows a consistent structure designed for procurement, legal, and compliance workflows.

You receive intelligence covering:

Corporate registration & identity
Ownership & shareholding structure
Subsidiaries and affiliated entities
Legal, regulatory, and enforcement records
Intellectual property holdings
Financial statements (where publicly available)
Digital presence & brand indicators
Government programs, subsidies, or violations
Competitive and industry benchmarking

Users may also request specific chapters only when a narrower scope is needed.

Why SupplyGraph AI?

SupplyGraph AI is powered by a global supply-chain intelligence graph built from:

100M+ companies worldwide
1M+ products and operational entities
8,000+ industry benchmarking datasets

This allows the system to produce due diligence intelligence that is:

Evidence-linked — every insight traces back to sourced information
Context-aware — enriched with industry and peer-group context
Continuously refreshed — updated on a rolling cycle
Designed for enterprise use — consistent, structured, and audit-friendly

Importantly, the system does not require uploading proprietary or internal corporate data.

Try the Automated Due Diligence Workflow (Live Demo)

Before integrating through API, you can experience the workflow via our interactive chatbot:

Live Demo:

https://supplygraph.ai/zk_chat_os/agentic/dialog.html?name=due_diligence_report

You can:

Enter a company name in natural language
Confirm the correct entity
Generate a full or chapter-specific due diligence report
Preview the structure and clarity of the generated intelligence

To access the demo:

Create a SupplyGraph AI account
Top up your credit balance

The chatbot uses the same A2A agent described in the developer documentation.

Developer Section: A2A API Overview

SupplyGraph AI provides a programmatic interface for embedding due diligence intelligence into procurement platforms, compliance workflows, or internal automation systems.

Endpoints

Endpoint	Method	Description
`/api/v1/agents/due_diligence_report/manifest`	GET	Retrieve metadata, schema, pricing, version info
`/api/v1/agents/due_diligence_report/run`	POST	Start or manage tasks

Run Example

curl -X POST https://agent.supplygraph.ai/api/v1/agents/due_diligence_report/run \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Tesla, Inc. United States", "stream": false }'

If confirmation is required:

{
  "code": "WAITING_USER",
  "data": {
    "content": "Here are the companies we’ve identified... Please reply Yes or No."
  }
}

Retrieve Results

curl -X POST https://agent.supplygraph.ai/api/v1/agents/due_diligence_report/run \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{ "mode": "results", "task_id": "<task-id>" }'

Build Your Own Workflows

The Due Diligence Agent integrates with:

SupplyGraph A2A protocol
Python SDK
Event-driven automation workflows
Multi-step investigation pipelines

SDK Repository:

https://github.com/SupplyGraphAI/supplygraphai_a2a_sdk

From Manual Research to Continuous Intelligence

Compliance expectations are rising. Supply chains are expanding. Third-party risk is accelerating.

Organizations that rely on manual research will fall behind.

Organizations that automate intelligence will move faster, operate safer, and make better decisions.

The Automated Due Diligence Agent helps teams transition from fragmented, static reporting to continuous, structured, and scalable supplier intelligence.

If this article was helpful, follow us on dev.to and GitHub for future deep dives into the SupplyGraph AI ecosystem.

GitHub → https://github.com/SupplyGraphAI

Automating U.S. Tariff Calculation with AI: A More Reliable Way to Navigate HTS + Chapter 99 Complexity

SupplyGraph.AI — Mon, 08 Dec 2025 02:18:31 +0000

Why Tariff Calculation Has Become So Difficult

For trade compliance teams, customs brokers, and global sourcing leaders, U.S. tariff determination has quietly become one of the most resource-intensive steps in trade operations. Even with internal systems and partial automation, teams still face several structural challenges:

1. Overlapping and fast-changing rule layers

The Harmonized Tariff Schedule (HTSUS) defines base duty rates, but Chapter 99 introduces hundreds of additional, suspended, conditional, or time-limited measures. These interact with Section 301, Section 232, presidential proclamations, temporary exclusions, and other notices — many of which can be updated with minimal lead time.

2. Highly specific eligibility conditions

Tariff outcomes can hinge on details such as:

Whether U.S.-origin content exceeds specific thresholds
Whether a shipment qualifies as a charitable donation
Whether an FTA applies
Whether a product’s classification carries conditional exceptions

Each requirement is straightforward on its own, but extremely difficult to evaluate consistently for large SKU catalogs.

3. Manual workflows that don’t scale

A typical duty calculation still requires:

Searching HTSUS tables
Reviewing Chapter 99 notes
Cross-checking trade measures
Verifying origin-dependent rules
Ensuring no exemptions or temporary measures were missed

Even experienced specialists may reach different results when interpreting the same product scenario — especially under time pressure.

Introducing SupplyGraph AI’s U.S. Tariff Calculation Agent

SupplyGraph AI provides an AI-assisted, traceable, regulation-aligned duty calculation workflow designed to reduce manual effort and improve consistency for organizations that handle recurring tariff assessments.

The Agent assists with:

Classifying products when only a description is provided
Applying base HTS rates
Checking all relevant Chapter 99 measures
Identifying applicable Section 301 / 232 / 201 implications
Evaluating country-of-origin impacts
Producing an explainable calculation trail

Every output is designed to be auditable and aligned with published U.S. regulatory sources.

It does not override, reinterpret, or predict regulatory decisions — it simply ensures teams can operationalize publicly available tariff rules with greater reliability.

Before vs. After: What Changes for Compliance Teams?

Before (Typical Workflow)

Searching HTS tables manually
Comparing multiple possible classifications
Reviewing each applicable Chapter 99 note
Checking for exclusions or expirations
Combining base duties + surcharges manually
Repeating the process for every minor variation

The process often takes 30–90 minutes per SKU, depending on complexity.

After (With AI Assistance)

Enter a product description or HTS code
Provide a country of origin
Receive an explainable calculation in seconds

Users still maintain full oversight — the system simply accelerates the analytical steps and centralizes all applicable rule references.

A suggested cover-image description for this section (if the platform generates images):

A split-screen diagram showing a manual, paper-heavy tariff calculation workflow on the left and an AI-assisted, structured calculation output on the right.

How It Works: Inside the TariffRAG™ Engine

The U.S. Tariff Calculation Agent is powered by TariffRAG™, a rule-aligned knowledge and reasoning system built specifically for tariff determination.

1. Structured ingestion of official sources

The system continuously processes:

HTSUS schedules
Chapter 99 notes
Federal Register notices
Presidential proclamations
Section 301 / 232 updates
CBP and USTR publications

All data is normalized into a structured ruleset that can be applied consistently.

2. Semantic parsing of conditional logic

Many tariff rules contain conditional language (e.g., “except when…”, “provided that…”, “notwithstanding…”).

The Agent interprets these conditions and transforms them into machine-applicable logic.

3. Logical chaining and applicability checks

When a user submits a scenario, the system:

Identifies the relevant HTS code(s)
Applies base duty rates
Evaluates all potentially applicable Chapter 99 provisions
Checks for conditions such as origin, donation status, exclusions, etc.

The final calculation includes a human-readable explanation outlining why specific provisions applied or did not apply.

The goal is not to replace compliance judgment — but to significantly reduce the mechanical workload behind each calculation.

What You Can Do Today

The U.S. Tariff Calculation Agent is available through:

A live chatbot demo for interactive classification + duty calculation
A2A (Agent-to-Agent) API integration for automated workflows
An open-source Python SDK for rapid developer adoption

Try the Live Chatbot

https://supplygraph.ai/zk_chat_os/agentic/dialog.html?name=tariff_calc

Explore the SDK on GitHub

https://github.com/SupplyGraphAI/supplygraphai_a2a_sdk

A More Scalable Way Forward

Organizations handling high-volume tariff assessments face a structural challenge: the regulatory environment will never get simpler, and manual workflows will never scale.

SupplyGraph AI’s approach focuses on:

Consistency — every calculation applies rules systematically
Transparency — all outcomes include traceable reasoning
Responsiveness — updates are synchronized frequently with official sources
Integration — use interactively or incorporate into existing systems

For teams managing hundreds or thousands of SKUs, this shifts tariff work from reactive, manual research to a more predictable operational process.

If your organization wants to modernize tariff operations or experiment with AI-assisted compliance infrastructure, the GitHub SDK is an easy starting point.

Want to Build With Us?

The Tariff Calculation Agent is one component of SupplyGraph AI’s broader multi-agent supply chain intelligence ecosystem.

If you’re interested in integrating tariff logic into your own workflows, agent systems, or procurement analytics tools, explore the SDK or reach out through GitHub.

Detecting Deep-Tier Geographic Concentration in Supply Chains Using AI

SupplyGraph.AI — Fri, 05 Dec 2025 09:35:00 +0000

How engineers can surface hidden upstream dependencies without access to proprietary supplier data.

Most supply-chain visibility tools stop at Tier-1. But the structural patterns that matter most — country-level concentration, single-region dependencies, and upstream bottlenecks — often emerge far deeper in the network, sometimes at Tier-4, Tier-6, or even Tier-10.

This raises a practical engineering question:

How can we algorithmically detect where a company’s upstream supply chain is dominated by one geography, even when no supplier lists or ERP data are available?

This article explains how SupplyGraph AI’s Geographic Concentration Analysis Agent uses graph inference, multi-hop traversal, and quantitative concentration metrics to surface these patterns — and how you can integrate it directly into your own system through our A2A API.

1. The Core Problem: Geographic Risk You Cannot See

Most enterprises do not have enough visibility to answer questions like:

Which upstream tiers depend heavily on a single country?
Which components lack geographic alternatives?
Where could a regional disruption propagate into upstream bottlenecks?

Even companies with globally diversified Tier-1 vendors may still have deep-tier segments showing very high geographic concentration — something not detectable through traditional supplier-declaration approaches.

These insights are often needed for:

compliance and ESG workflows
due-diligence automation
internal supply-chain risk dashboards
strategic sourcing assessments

This is where graph-based inference becomes useful.

2. The Graph-Based Approach (How We Model Upstream Structure)

Instead of relying on declared supplier lists, the agent uses a global enterprise–product knowledge graph, encoding:

enterprises
products
product-inclusion structures
geographic attributes

By chaining product-inclusion relationships, we can infer likely multi-tier upstream structures.

⚠ Important Clarification

This graph does not represent:

transactional supplier relationships
purchase-order data
proprietary vendor lists
verified supply-chain certifications

It reflects inferred, probabilistic upstream pathways, not a reconstruction of any company’s official supply chain.

An abstraction of the graph:

Enterprise → makes → Product → includes → Component → made_by → Enterprise

Different industries exhibit different reachable depths; some may reach eight or more tiers, while others are shallower.

3. What the Geographic Concentration Analysis Agent Does

1) Multi-hop traversal

Builds an inferred multi-tier upstream structure based on product-inclusion logic.

2) Geographic segmentation

Maps each enterprise node to country and region attributes.

3) Quantitative concentration scoring

Using models such as:

HHI = Σ (share_i²)
dominance_ratio = count(country) / total

4) Substitutability scan

Identifies whether other regions appear in the graph for the same upstream segment.

This reflects only graph-level presence — not commercial availability, qualification status, or procurement feasibility.

5) Structured, transparent reporting

Including geographic dominance, HHI metrics, segment summaries, and evidence chains.

The output is analytical and informational; it is not a regulatory audit or compliance determination.

4. Example Output (Simplified)

{
  "segment": "Tier-4 Electronics Components",
  "dominant_region": "China",
  "dominance_ratio": 0.91,
  "hhi": 0.87,
  "alternatives_exist": true,
  "evidence": [
    "enterprise_A → component_X → product_Y",
    "enterprise_B → component_X → product_Y"
  ]
}

In practice, the agent produces a rich Markdown report with detailed explanations.

5. Try the Agent Interactively

You can explore the agent with no integration required:

https://supplygraph.ai/zk_chat_os/agentic/dialog.html?name=sg_chokepoint

Just enter a company name.

Entity matching is performed automatically.

6. A2A API Integration Guide

Developers can integrate the agent into analytics pipelines, internal dashboards, ETL flows, or risk-modeling services.

🔹 Manifest: Retrieve schema & pricing

curl -X GET https://agent.supplygraph.ai/api/v1/agents/sg_chokepoint/manifest \
  -H "Authorization: Bearer <YOUR_API_KEY>"

🔹 Run Analysis Task

curl -X POST https://agent.supplygraph.ai/api/v1/agents/sg_chokepoint/run \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Company Name",
    "stream": true
  }'

Notes:

"text" accepts a natural-language company name
Entity resolution is handled internally
Streaming may return: THINKING, TASK_ACCEPTED, TASK_RUNNING

🔹 Check Task Status

curl -X POST https://agent.supplygraph.ai/api/v1/agents/sg_chokepoint/run \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"mode":"status","task_id":"<id>"}'

🔹 Retrieve Final Results

curl -X POST https://agent.supplygraph.ai/api/v1/agents/sg_chokepoint/run \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{"mode":"results","task_id":"<id>"}'

Example:

{
  "success": true,
  "data": {
    "content": "## Concentration Analysis Report ..."
  },
  "metadata": {
    "credits_used": 10
  }
}

7. Where This Fits in Engineering & Analytics Work

✔ Compliance & ESG automation

Support documentation workflows with explainable metrics.

(Not a certification or regulatory determination.)

✔ Risk dashboards

Incorporate upstream geographic concentration metrics into internal UIs.

✔ Procurement analytics

Highlight hidden dependencies during supplier onboarding or category planning.

✔ Geopolitical risk modeling

Use concentration metrics as inputs to scenario simulations.

✔ Data science pipelines

Engineer HHI-based features for ML or forecasting models.

8. One Sentence Summary

If your visibility stops at Tier-1, you’re blind to the most important geographic risks in your supply chain.

This agent exposes those deep-tier dependencies — analytically, transparently, and at scale — using graph-based inference.

9. GitHub (A2A SDK + Examples)

➡️ https://github.com/SupplyGraphAI/supplygraphai_a2a_sdk

If this project is useful, consider leaving a ⭐ to help others discover it.

Building an AI-Powered HTS Classifier: A Technical Breakdown of SupplyGraph AI’s Customs Classification Agent

SupplyGraph.AI — Thu, 04 Dec 2025 07:24:48 +0000

HTS classification looks simple on paper — but anyone working in trade automation knows it isn’t. It’s a problem full of ambiguity, nested rules, overlapping categories, and legally precise exceptions. And despite being a high-impact step in global trade, most teams still rely on manual lookup and inconsistent human interpretation.

In this post, I’ll walk through how we engineered the Customs Classification Agent at SupplyGraph AI using a hybrid retrieval + constrained-reasoning approach, exposed through our A2A (Agent-to-Agent) protocol. This is a technical deep dive intended for developers, not a marketing overview.

You'll learn:

what makes HTS classification uniquely difficult
why embeddings and raw LLM prompts fail
how our retrieval layer, scoring engine, and reasoning layer work together
how the A2A protocol structures task execution
how to run the agent using cURL or Python SDK
where to find the SDK and examples on GitHub

Let’s get into it.

Why HTS Classification Is a Hard Engineering Problem

HTS classification has several properties that make it a non-trivial task for search, rule-based, and ML systems:

legal text doesn’t follow natural-language conventions
category boundaries are often implied, not explicit
products may match multiple plausible codes
correctness depends on combinations of attributes (material + form + use)
legal notes introduce exceptions, inclusions, and cross-references
tariff schedules update regularly and must remain version-locked for audits

From an engineering perspective, this resembles hierarchical, legal-style reasoning, rather than simple tagging.

Why common approaches fall short

Embeddings alone

They struggle with:

hierarchical structure
exclusion rules
multi-attribute dependencies
long-range legal references

Raw LLM classification

Common failure cases:

hallucinating subheadings
reasoning without grounding in legal text
no version control
no reproducibility
no audit trail

HTS classification benefits from structured grounding, deterministic protocol behavior, and explainability—not just LLM power.

⚙ Architecture Overview

Our classification pipeline:

Product Description
       ▼
 Pre-processing
       ▼
 Attribute Extraction
       ▼
 Candidate Retrieval
 (HTS text + notes + enriched nodes)
       ▼
 Candidate Scoring
       ▼
 Constrained Reasoning
 (grounded evaluation, no free-form generation)
       ▼
 Ranked HTS Classification

Engineering clarifications

The retrieval layer searches a structured dataset containing HTS text + legal notes + derived attribute nodes, not a million HTS entries.
The reasoning layer is LLM-based but constrained, operating strictly over grounded candidate data.
Confidence score is a normalized ranking score, not a calibrated statistical probability.
Every output is tied to a specific tariff dataset version for audit reproducibility.

🔌 The A2A Protocol: How the Agent Exposes Its Interface

A2A defines:

stable event types
deterministic protocol flow
explicit state transitions (interpreting → executing → completed)
optional SSE streaming
the WAITING_USER step when multiple interpretations are possible

Agents expose:

/manifest
/run  (mode=run | status | results)

This keeps agent interactions simple but predictable.

📄 Manifest Example

GET /api/v1/agents/tariff_classification/manifest

{
  "agent_id": "tariff_classification",
  "name": "Customs Classification Agent",
  "version": "1.0.0",
  "description": "Maps product descriptions to HS/HTS codes.",
  "pricing": { "per_run": 2, "unit": "credits" },
  "input_schema": {...},
  "output_schema": {...}
}

🚀 Running a Classification Task

Non-streaming

curl -X POST https://agent.supplygraph.ai/api/v1/agents/tariff_classification/run \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
        "mode": "run",
        "text": "Knitted cotton T-shirt for women"
      }'

Example Output

{
  "success": true,
  "code": "TASK_COMPLETED",
  "data": {
    "content": {
      "type": "result",
      "data": {
        "classification_results": [
          {
            "hts_code": "6109.10.00.40",
            "confidence_score": 0.90,
            "reasoning": "Identified as knitted cotton T-shirt for women.",
            "description": "T-shirts, singlets, tank tops... of cotton; women's or girls'"
          }
        ],
        "country_of_origin": "Mexico"
      }
    }
  }
}

✔ Note:

country_of_origin only appears when explicitly present in the input text.

The agent does not infer origin automatically.

📡 Streaming Reasoning via SSE

Enable streaming with:

stream=true

Example events:

event: stream
data: { "stage": "interpreting", "reasoning": ["Extracting product attributes..."] }

event: stream
data: { "stage": "executing", "code": "TASK_ACCEPTED" }

event: end
data: [DONE]

Helpful for interactive UIs and debugging.

Python SDK Example

Repo: https://github.com/SupplyGraphAI/supplygraphai_a2a_sdk

from supplygraph.compat import OpenAICompatibleClient

client = OpenAICompatibleClient(api_key="sg-xxx")

response = client.agents.run(
    "tariff_classification",
    text="Machine-cut aluminum sheets, thickness 2.5mm"
)

print(response)

Streaming:

for event in client.agents.stream("tariff_classification", text="..."):
    print(event)
}

📁 Output Structure

Field	Meaning
`hts_code`	Suggested classification
`confidence_score`	Ranking score (normalized 0–1)
`reasoning`	Constrained, grounded explanation
`description`	Official HTS text
`country_of_origin`	Included only when present in input

Outputs are designed for direct integration with:

duty estimation
ERP flows
compliance review
audit logging

🔍 Why This Hybrid Approach Works

Problem	Our solution
Embeddings miss legal boundaries	Structured retrieval
LLMs hallucinate	Constrained reasoning
No repeatability	Protocol-level determinism
No audit trail	Version-locked datasets
Ambiguous inputs	`WAITING_USER` clarification

This yields a classifier that’s transparent, explainable, and suitable for production environments.

🔗 GitHub & Resources

Python SDK

https://github.com/SupplyGraphAI/supplygraphai_a2a_sdk

All repositories

https://github.com/SupplyGraphAI

Contributions, issues, and discussions are welcome.

🏁 Closing Thoughts

HTS classification is deceptively difficult because it blends legal-style logic with multi-attribute categorization. Our approach combines retrieval, scoring, and constrained reasoning, then exposes it through a predictable A2A protocol that developers can embed directly into their systems.

As always, final HTS determination depends on complete product details and applicable legal notes.

This agent supports — but does not replace — professional judgment in tariff classification.

If you'd like a deeper dive into the retrieval engine or A2A internals, I’m happy to write a Part 2.

How We Build a Tier-10 Global Supply Graph

SupplyGraph.AI — Wed, 03 Dec 2025 03:05:55 +0000

Engineering the data, architecture, and reasoning behind deep-tier supply chain visibility

Most teams can only see Tier-1 suppliers.

Some advanced organizations map parts of Tier-2 or Tier-3.

But almost no system today can reliably expose the deeper layers—Tier-4 to Tier-10—where the majority of structural supply chain risk actually lives.

This article breaks down the engineering principles, system design, and data modeling approach behind building a Tier-10 global supply graph — not as a monolithic platform, but as a foundation for modular, A2A-compatible agents that developers can integrate directly into real systems.

Why Tier-1 Visibility Fails in Modern Supply Chains

A single product may depend on:

dozens of Tier-1 suppliers
hundreds of Tier-2/3 suppliers
thousands of deeper-tier producers, refiners, and upstream transform nodes

Yet 80%+ of enterprises today have visibility only into Tier-1.

This creates well-known problems:

hidden single-source dependencies
exposure to upstream geopolitical or natural-disaster risks
unexpected compliance violations
inaccurate business continuity planning
inability to quantify concentration risk

In other words:

Risk originates deep in the chain—but most tools only show the surface.

To solve this, we needed a continuously updated global supply graph representing multi-tier dependencies across industries, geographies, product categories, and transformation processes.

What We Mean by a “Tier-10 Supply Graph”

A Tier-10 map is not a static supplier list.

It is a graph that expresses:

enterprises
industrial products
material transformations
production relationships
geographic footprints
dependency edges across 10+ upstream hops

At this depth, the graph is no longer a simple hierarchy. It becomes a large-scale, sparse, heterogeneous knowledge network.

Our implementation currently spans:

100M+ enterprises
millions of industrial products
multi-hop dependency paths up to Tier-10
thousands of daily updates from public and permissible sources

These numbers represent a modeled knowledge graph built from globally available public data sources, structured signals, and proprietary transformation pipelines — not raw access to private data.

Core Engineering Challenges

Building a Tier-10 supply graph presented several significant engineering hurdles.

1. Unifying Heterogeneous Data at Scale

Supply chain data is inherently fragmented:

corporate registries
product catalogs
industrial classification systems
logistics data
trade flows
news and regulatory signals
technological capability descriptions
ESG and compliance metrics

No single source covers everything. The graph must merge, resolve conflicts, normalize fields, and infer missing structure.

2. Modeling Multi-Hop Dependencies

A product is rarely made from a single input.

It passes through transform chains:

raw material → precursor → component → module → system → finished good

Each stage may occur in different countries, under different risk profiles.

This is why Tier-10 mapping matters:

disruptions rarely stop at Tier-2 or Tier-3.

3. Updating the Graph Continuously

The world changes every day:

factory shutdowns
sanctions
policy shifts
mergers & acquisitions
natural disasters
export controls
price/volume shocks

The supply graph must incorporate new signals without rebuilding the entire network.

We designed an incremental update pipeline with:

entity/event detectors
dependency refresh rules
risk-type annotations
propagation scoring models

The goal is continuous updating, not “real-time prediction.”

4. Representing Risk Propagation

A supply graph is not useful unless it can express:

where disruptions originate
how they travel
which enterprises/products are exposed
which nodes act as amplifiers or buffers

This requires graph-propagation logic, not static dashboards.

The Architecture Behind the Tier-10 Graph

At a high level, the system has four major layers.

1. Ingestion Layer

Collects and normalizes:

corporate entity data
product descriptions
industrial classification trees
open regulatory signals
logistics + trade indicators
manufacturing transformation hints

All sources must be permissible and transparently traceable.

2. Entity + Product Resolution Layer

Performs:

deduplication
clustering
multi-field entity matching
product canonicalization

Consistency at this stage determines graph quality.

3. Dependency Construction Layer

Builds directed edges using:

text-driven extraction
product transformation models
co-occurrence signals
supply-path inference
industry-specific logic

Edges represent probabilistic but explainable relationships.

4. Graph Intelligence Layer

Provides:

multi-hop traversal
dependency expansion to Tier-10
concentration analysis (HHI, clustering, country exposure)
risk propagation scoring
evidence retrieval
A2A-compatible structured outputs

This is also where downstream agents—SupplyGraph Visualization, Concentration Analysis, Due Diligence—retrieve graph-based reasoning.

Why Developers Use the Tier-10 Graph Through A2A Agents

Rather than forcing teams to query the raw graph, we expose capabilities through modular A2A agents:

supply-graph visualization
multi-hop dependency extraction
risk propagation analysis
geographic concentration scoring
enterprise due diligence

Each agent implements:

a clear input schema
deterministic structured outputs
optional long-running jobs
evidence paths
transparent reasoning

This makes integration simple for:

procurement systems
compliance automation
supply chain analytics
internal developer tools
risk monitoring pipelines

No new platform needed.

Just composable building blocks.

What This Enables

A Tier-10 supply graph allows organizations to answer questions that traditional systems simply cannot:

“Which upstream nodes expose us to geopolitical risk across 6+ tiers?”
“What are the hidden dependencies behind this product?”
“How will a new export control propagate into our supply base?”
“Which single-region chokepoints exist beyond Tier-3?”
“What concentration risks exist across our entire product portfolio?”

These are not abstract problems—they define whether a company can operate reliably in a volatile world.

Explore the Specification

The supply graph itself is not a monolithic product.

It is the underlying intelligence layer powering a set of open A2A-compatible agents.

Documentation and examples are available here:

👉 https://github.com/SupplyGraphAI/supplygraph-ai

If you work on supply chain engineering, risk modeling, or multi-hop dependency systems, we’d love to hear how you approach similar challenges.

A Practical A2A Protocol for Supply Chain Intelligence

SupplyGraph.AI — Tue, 02 Dec 2025 06:41:37 +0000

A lightweight pattern for exposing modular capabilities without creating a monolith

Note: In this article, “agents” refers to modular capability units — not LLM orchestrators or swarm-style multi-agent systems.

Supply chain operations rarely fit inside a simple request–response cycle.

Classification, tariff evaluation, dependency mapping, due diligence checks — all of them unfold across multiple dependent steps. Yet most API designs still assume these workflows are instantaneous.

While developing large-scale supply chain intelligence systems—multi-tier supplier graphs, risk propagation logic, compliance engines, tariff models—a recurring challenge emerged:

How do you expose complex, multi-step logic without forcing complexity onto the caller?

A lightweight A2A (Agent-to-Agent) protocol proved to be an effective solution — not as a product feature, but as a generalizable integration pattern for long-running or multi-step API workflows.

This article breaks down the reasoning behind the pattern and why it works well in practice.

Why Traditional APIs Struggle With Multi-Step Workflows

On the surface, workflows like “classify a product” or “calculate tariff duties” look atomic. In reality, they decompose into multiple phases:

input normalization
attribute inference
rule and exception matching
multi-country tariff overlays
multi-hop dependency expansion
evidence collection and assembly

Bundling these processes into a single synchronous call leads to:

unpredictable execution times
brittle timeout handling
opaque branching logic
unclear error reporting
monolithic endpoints that quickly become unmanageable

The issue isn’t performance.

It’s the lack of an API abstraction that expresses multi-step workflows cleanly.

Why a Lightweight A2A Pattern Works

Instead of a massive all-in-one endpoint, a system can be decomposed into small, focused capability units, each responsible for exactly one task:

classification
tariff calculation
dependency graph expansion
concentration analysis
due diligence synthesis

Each capability exposes a simple lifecycle:

run — start the task
status — check progress
result — fetch the final structured output

This keeps the surface area predictable while allowing internal logic to remain expressive.

The A2A Lifecycle (with Examples)

A2A follows three predictable operations:

caller → POST /run      → task_id
caller → GET /status    → pending | running | done | failed
caller → GET /result    → structured output

This minimal protocol is intuitive, flexible, and maps naturally to complex workflows.

1. `run` — Start a task (idempotent)

POST /agents/hts_classification/run
{
  "product_description": "EV lithium battery pack",
  "idempotency_key": "client-123"
}

Response:

{
  "task_id": "abc123",
  "status": "PENDING"
}

Idempotency keys allow safe retries — essential in distributed environments.

2. `status` — Monitor progress

GET /agents/hts_classification/status?task_id=abc123

Response:

{
  "status": "RUNNING",
  "progress": 0.4,
  "steps": ["normalize_input", "attribute_inference"]
}

For multi-second or multi-minute workflows, clients typically poll every 1–3 seconds.

3. `result` — Retrieve structured output

GET /agents/hts_classification/result?task_id=abc123

Response:

{
  "hts_code": "8507.60.0020",
  "confidence": 0.94,
  "evidence": {
    "matched_phrases": ["lithium-ion", "battery pack"],
    "rule_path": ["chapter 85", "heading 07", "subheading 60"]
  }
}

Output schemas remain deterministic even when internal components use constrained LLM reasoning.

Error Handling (A Required Part of the Pattern)

A2A provides a consistent, machine-readable structure for failures:

{
  "status": "FAILED",
  "error": {
    "type": "VALIDATION_ERROR",
    "message": "Missing required field: product_description",
    "fields": ["product_description"]
  }
}

Predictable error semantics significantly reduce integration friction.

Why A2A Works Well for Supply Chain Intelligence

✔ 1. It mirrors real multi-step workflows

Developers gain an API abstraction that matches actual execution semantics.

✔ 2. It keeps capabilities independent

Classification logic stays focused on classification; tariff logic stays focused on tariff computation.

✔ 3. It supports long-running jobs cleanly

Whether expanding Tier-10 supplier networks or aggregating due diligence signals, long tasks run safely without timeouts.

✔ 4. It improves transparency and auditability

Each capability has a single responsibility and a deterministic schema.

✔ 5. It avoids monolithic surface areas

Developers integrate only the components they need.

A2A Is Not an Orchestration Framework

A2A does not prescribe:

how workflows execute internally
which compute model is used
whether logic is rule-based, graph-based, or LLM-based
whether async execution uses queues, workers, or distributed pipelines

A2A simply defines how capabilities expose themselves.

This avoids a common misunderstanding:

A2A is an integration pattern, not a multi-agent runtime.

When A2A Outperforms Traditional APIs

Choose synchronous APIs for:

small
atomic
single-step
instant operations

Choose A2A for workflows that are:

multi-step
long-running
reasoning-dependent
requiring deterministic schemas
naturally modular

Explore the Open Specification

The complete open specification — including lifecycle semantics, schemas, error models, and runnable examples — is available here:

👉 https://github.com/SupplyGraphAI/supplygraph-ai

The repository contains:

formal manifest definitions
structured I/O schemas
consistent error semantics
example agents
reference clients
integration quickstarts

The spec continues to evolve as more capabilities are added across supply chain intelligence:

multi-tier dependency expansion
risk propagation modeling
tariff and compliance automation
due diligence aggregation
geographic concentration scoring

If you’ve worked on similar multi-step API designs or long-running workflows, I’d love to hear how you approached them.