Python Agent SDK
Benchmarked against: Anthropic — Python Agent SDK Line: Line 2 (LangGraph Self-Built) Key files:
superportia_agent.py,supervisor.pyEcosystem: LangGraph 1.0.8 + langchain-mcp-adapters 0.2.1
The Python SDK for SuperPortia agents is built on LangGraph — the graph-based agent framework. It provides persistent state, multi-agent orchestration, and integration with any AI engine.
Installed ecosystem (SS1)
| Package | Version | Purpose |
|---|---|---|
langgraph | 1.0.8 | Agent graph framework |
langgraph-checkpoint-sqlite | 3.0.3 | State persistence |
langchain-mcp-adapters | 0.2.1 | MCP tool integration |
Architecture
Flat vs. nested mode
| Mode | Engines | How it works |
|---|---|---|
| Flat | Groq, DeepSeek, Mistral, Zhipu | Supervisor directly calls tools |
| Nested | Gemini, Claude | Supervisor delegates to worker agents |
Why the split: Groq uses XML tool calling format, which breaks nested agent-as-tool patterns. supervisor.py auto-detects and switches.
Key components
State management
from langgraph.graph import StateGraph, MessagesState
graph = StateGraph(MessagesState)
State persists across turns via SQLite checkpoints:
from langgraph.checkpoint.sqlite import SqliteSaver
memory = SqliteSaver.from_conn_string(":memory:")
app = graph.compile(checkpointer=memory)
MCP tool integration
from langchain_mcp_adapters import MCPToolkit
toolkit = MCPToolkit(server_config={...})
tools = await toolkit.get_tools()
Note: MCP tools require async invocation (ainvoke).
Token baselines
From SS1 measurements (2026-02-26):
| Metric | Value |
|---|---|
| Single Q&A + 1 tool call (Sonnet) | 20,677 input + 102 output tokens |
| Tool descriptions for 35 tools | ~4,103 tokens |
| Role-based tool subset (10 tools) | ~1,200 tokens |
Optimization: Assign role-based tool subsets to reduce description tokens.
Multi-agent orchestration
supervisor.py enables multi-agent patterns:
from supervisor import create_supervisor
supervisor = create_supervisor(
workers=["researcher", "coder", "reviewer"],
engine="gemini", # auto-selects nested mode
)
result = await supervisor.invoke({"task": "Research and implement..."})
Limitations
| Limitation | Impact | Status |
|---|---|---|
| No direct file operations | Can't edit files via LangGraph agents | Use Claude engine for file WOs |
| Groq XML tool format | Breaks nested mode | Auto flat mode switch |
| Token explosion with ingest_text | Groq generates garbage Unicode | Ingest handled at orchestrator |
| No streaming support | Can't stream partial results | Planned |
Related pages
| Page | Relationship |
|---|---|
| Agent SDK Overview | Dual lines architecture |
| LangGraph Quickstart | Step-by-step tutorial |
| Line Migration | Moving between lines |
| Engine Overview | Available engines |