SupplyGraph AI – A2A Python SDK (Developer Lite Guide)

1. Initialize Client

from supplygraphai_a2a_sdk import AgentClient

client = AgentClient(
    api_key="YOUR_API_KEY",
    base_url="https://agent.supplygraph.ai/api/v1/agents"
)

2. High-Level Agent Wrapper (Recommended)

from supplygraphai_a2a_sdk import USTariffCalculationAgent

agent = USTariffCalculationAgent(client)

resp = agent.run("Importing 100kg of ice cream from China")
print(resp)

3. A2A Response Structure (Simplified for Developers)

Every agent response follows this envelope:

{
  "success": true,
  "code": "WAITING_USER",
  "message": "Please provide the country of origin.",
  "data": {
    "task_id": "tsk_xxx",
    "stage": "interpreting",
    "code": "WAITING_USER",
    "content": "Please specify the country."
  }
}

Developer essentials:

• code → Primary state (WAITING_USER, TASK_ACCEPTED, TASK_RUNNING, TASK_COMPLETED, etc.)
• data.task_id → Used to continue the same task
• data.content → Response content (text or structured JSON)
• message → Always safe to show to user

4. Multi-Step Workflow (Core Developer Logic)

A2A tasks often require:

• Initial run
• Agent requests more info (WAITING_USER)
• Continue with task_id
• Agent accepts task (TASK_ACCEPTED)
• Task runs (TASK_RUNNING)
• Complete (TASK_COMPLETED) → call results()

Here is the full recommended implementation:

resp = agent.run("Import 100kg ice cream")
task_id = resp["data"]["task_id"]
code = resp["code"]

while True:

    # --- Interpreting Stage ---
    if code == "WAITING_USER":
        print(resp["message"])
        user_reply = input("> ")
        resp = agent.run(text=user_reply, task_id=task_id)
        code = resp["code"]
        continue

    if code == "INVALID_REQUEST":
        print("Invalid:", resp["message"])
        break

    if code == "UNAUTHORIZED":
        print("API key invalid.")
        break

    # --- Executing Stage ---
    if code == "TASK_ACCEPTED":
        resp = agent.status(task_id)
        code = resp["code"]
        continue

    if code == "TASK_RUNNING":
        import time; time.sleep(1)
        resp = agent.status(task_id)
        code = resp["code"]
        continue

    # --- Completed Stage ---
    if code == "TASK_COMPLETED":
        result = agent.results(task_id)
        print("Final:", result["data"]["content"])
        break

    if code == "TASK_FAILED":
        print("Task failed:", resp["message"])
        break

5. Handling data.content (Text & Structured JSON)

content = resp["data"]["content"]

if isinstance(content, str):
    print("Text:", content)

elif isinstance(content, dict) and content.get("type") == "result":
    print("Structured:", content["data"])

6. Streaming Mode (THINKING events)

SSE frames:

{
  "event": "stream",
  "data": {
    "code": "THINKING",
    "reasoning": ["..."]
  }
}

Developer usage:

events = agent.run("Import 100kg citrus", stream=True)

for ev in events:
    for r in ev["data"]["reasoning"]:
        print("> ", r)

7. Fetching Manifest

manifest = client.manifest("tariff_classification")
print(manifest["pricing"])
print(manifest["input_schema"])

8. Custom Agent Wrapper

from supplygraphai_a2a_sdk.client.base_agent import BaseAgent

class MyCustomAgent(BaseAgent):
    def __init__(self, client):
        super().__init__(client, agent_id="my_custom_agent")

agent = MyCustomAgent(client)
print(agent.run("Hello"))

9. Adapter Ecosystem (Quick Reference)

The SDK includes first-class adapters for popular agent and tooling ecosystems. These adapters are optional and only needed when you integrate with a specific framework.

Supported ecosystems include (non-exhaustive):

• Google A2A
• AutoGen
• LangChain
• LangGraph
• Semantic Kernel
• CrewAI
• DSPy
• Flowise
• LlamaIndex
• MCP (ChatGPT, Cursor, Zed, etc.)
• BentoML
• Haystack
• Airflow

Each adapter:

• Wraps a SupplyGraph A2A Agent as a native tool / node / skill / runner
• Has no hard dependency inside the SDK (you install the framework in your own project)
• Uses the same A2A lifecycle: run → status → results with task_id and streaming support

Adapter-specific usage examples and best practices are provided in the dedicated docs (e.g. docs/adapters/langgraph_adapter.md, docs/adapters/crewai_adapter.md, etc.).

10. Related Documentation

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