Welcome to the SupplyGraph AI Developer Platform — the gateway to accessing autonomous supply-chain intelligence through our A2A/MCP interfaces.
This guide walks you through the essentials: creating an account, managing credits, generating an API key, and making your first request.
Once signed in, you’ll have access to:
SupplyGraph AI uses a credit-based pay-as-you-go model.
Each A2A or MCP request deducts a small number of credits, depending on the agent used.
💡 You only pay for what you use — there are no recurring fees unless you subscribe to enterprise plans.
All A2A and MCP integrations require authentication via an API key.
⚠️ A2A/MCP keys are personal credentials.
SupplyGraph AI provides Sandbox API Keys that allow developers to test integrations safely — without consuming credits — while still returning valid, schema-compliant responses.
A Sandbox Key behaves like a Production Key in terms of request format, authentication, and task lifecycle (run → status → results).
However, the returned data does not come from real-time agent computation. Instead, each agent returns preconfigured mock data or sample real data, depending on the agent type.
Sandbox responses fall into two categories depending on the agent:
A. Agents Returning Mock Data
These agents return fully simulated outputs, designed to match the official output schema but not based on real data:
These responses allow developers to validate:
B. Agents Returning Predefined Real Sample Data
These agents return fixed, realistic outputs derived from preset sample companies (e.g., Tesla or BYD).
These are not user-specific and do not reflect real-time queries, but they are authentic examples of actual agent outputs.
Agents using predefined real sample data:
These allow developers to:
local-dev, ci-test, or mock-environmentRecommended Usage
SupplyGraph AI follows a task-based A2A architecture:
run → status → results.
The same endpoint is used for all stages, controlled by the mode field.
Below is a minimal example using the Tariff classification Agent:
Purpose: Start a new task by providing a product description.
curl -X POST https://agent.supplygraph.ai/api/v1/agents/tariff_classification/run \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"text":"Cotton T-shirts for women, 100% cotton, made in Mexico", "stream": true}'
Example Response:
data: {"event": "stream", "data": {"task_id": "<system-generated-task-id>", "agent": "tariff_classification", "stage": "interpreting", "code": "THINKING", "progress": 0, "reasoning": ["Attempting to extract the HTS code and country of origin from the input text."], "timestamp": "2025-11-10T09:51:58.457382+00:00", "is_final": false}}
data: {"event": "stream", "data": {"task_id": "<system-generated-task-id>", "agent": "tariff_classification", "stage": "interpreting", "code": "THINKING", "progress": 0, "reasoning": ["Matched 20 related HTS codes. Assessing their relevance and matching accuracy."], "timestamp": "2025-11-10T09:52:06.518056+00:00", "is_final": false}}
data: {"event": "stream", "data": {"task_id": "<system-generated-task-id>", "agent": "tariff_classification", "stage": "interpreting", "code": "THINKING", "progress": 0, "reasoning": ["Processing in progress — please hang tight."], "timestamp": "2025-11-10T09:52:14.077191+00:00", "is_final": false}}
data: {"success": true, "code": "TASK_ACCEPTED", "message": "Task accepted and queued for execution.", "data": {"task_id": "<system-generated-task-id>", "agent": "tariff_classification", "stage": "executing", "code": "TASK_ACCEPTED", "progress": 0, "reasoning": [], "timestamp": "2025-11-10T09:52:34.557890+00:00", "is_final": true, "content": "task accepted"}, "metadata": {"agent": "tariff_classification", "timestamp": "2025-11-10T09:52:34.557922+00:00"}, "errors": null}
event: end
data: [DONE]
This is a streaming example for visibility into the agent’s thinking process. For a non-streaming version, simply set
"stream": false.
Purpose: Query the current status of the task using the same task_id.
curl -N -X POST https://agent.supplygraph.ai/api/v1/agents/tariff_classification/run \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-d '{"stream": true, "task_id": "<system-generated-task-id>", "mode": "status"}'
Example Response:
data: {"success": true, "code": "TASK_COMPLETED", "message": "Task completed successfully.", "data": {"task_id": "<system-generated-task-id>", "agent": "tariff_classification", "stage": "completed", "code": "TASK_COMPLETED", "progress": 100, "reasoning": [], "timestamp": "2025-11-10T10:03:50.442559+00:00", "is_final": true, "content": ""}, "metadata": {"agent": "tariff_classification", "timestamp": "2025-11-10T10:03:50.442601+00:00", "credits_used": 0.0}, "errors": null}
event: end
data: [DONE]
Purpose: Once the task is complete, request the final content.
curl -N -X POST https://agent.supplygraph.ai/api/v1/agents/tariff_classification/run \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-d '{"stream": true, "task_id": "<system-generated-task-id>", "mode": "results"}'
Example Response:
data: {"success": true, "code": "TASK_COMPLETED", "message": "Task completed successfully.", "data": {"task_id": "<system-generated-task-id>", "agent": "tariff_classification", "stage": "completed", "code": "TASK_COMPLETED", "progress": 100, "reasoning": [], "timestamp": "2025-11-10T10:04:49.748779+00:00", "is_final": true, "content": "##Best match:\nHTS code: 6109.10.00.40\n\n##Other possible HTS codes include:\n-6109.10.00.70: This code is for 'T-shirts, singlets, tank tops and similar garments, knitted or crocheted > Of cotton > Women's or girls' > Other > Other'. While the primary description is for T-shirts, this code could apply if the T-shirts have features that do not fit the more specific T-shirt category, but it is less likely given the straightforward description.\n-6114.20.00.10: This code is for 'Other garments, knitted or crocheted > Of cotton > Tops > Women's or girls''. While the product is specifically a T-shirt, this code could be considered if the T-shirts are categorized more broadly as tops, but it is less specific than the primary code."}, "metadata": {"agent": "tariff_classification", "timestamp": "2025-11-10T10:04:49.748823+00:00", "credits_used": 10}, "errors": null}
event: end
data: [DONE]
| Protocol | Description | Docs |
|---|---|---|
| A2A (Agent-to-Agent) | Native protocol for autonomous agent workflows and communication | A2A Protocol |
| MCP (Multi-Channel Protocol) | Next-generation orchestration protocol for enterprise and multi-system environments | (Coming Soon) |
| Interface | Description | Docs |
|---|---|---|
| Python SDK (A2A Client) | Official Python wrapper built on top of the A2A protocol for rapid integration | supplygraphai_a2a_sdk |
All responses include a unified status field and optional credits_used key.
Common errors:
| Code | Description |
|---|---|
UNAUTHORIZED |
API key missing or expired |
INSUFFICIENT_CREDITS |
Not enough credits for this request |
RATE_LIMITED |
Too many requests — try again later |
INVALID_REQUEST |
Request is outside the current agent’s scope |
Explore more about the SupplyGraph AI ecosystem:
📘 Getting Started Guide
https://github.com/SupplyGraphAI/supplygraph-ai/blob/main/docs/getting-started.md
🤖 Agent Specifications & Library
https://github.com/SupplyGraphAI/supplygraph-ai/tree/main/docs/agents
🧠 SupplyGraph AI Documentation Hub
https://github.com/SupplyGraphAI/supplygraph-ai
📦 Python A2A SDK (Official Repository)
https://github.com/SupplyGraphAI/supplygraphai_a2a_sdk
🌐 Official Website & Use Cases
https://www.supplygraph.ai
📄 Future Protocols & Enterprise Specifications (Coming Soon)
MCP, multi-agent orchestration & deployment whitepapers
© 2025 SupplyGraph AI, Inc. All rights reserved.