You run `pip install langchain openai` and wait. The resolver crawls through 847 packages before settling on a version. You finally get to code — but the LLM agent you built last month now has 14 import errors and the documentation moved twice. Python for AI agents is messy, fragmented, and moving faster than any other ecosystem in tech. And yet it remains the default. Here is why — and what changed in the first quarter of 2026.
In this tutorial, you will learn to:
- Understand why Python dominates AI agent frameworks despite the fragmentation
- Identify which new lightweight frameworks gained production traction in Q1 2026
- Build a working MCP server in Python using the official SDK and FastMCP
- Design multi-agent systems using supervisor, peer-to-peer, and hierarchical patterns
Page Contents
Prerequisites
You should have Python 3.10+ installed and be comfortable with virtual environments and pip. Familiarity with async/await patterns helps for the multi-agent sections. If you are new to async Python, start with our Python Async/Await: Complete Guide.
Why Python Remains the Default Language for AI Agents
Every major AI agent framework — LangChain, LlamaIndex, CrewAI, AutoGen — ships a Python-first API. The reason is not accidental. Python’s dynamic typing, interpreted nature, and mature ecosystem for data processing (pandas, numpy, requests) make it the natural substrate for LLM-heavy workloads. You can prototype an agent that calls a tool, manages memory, and reasons in under 50 lines. No compilation step, no type ceremony.
Python also has the largest ML talent pool. When a new model provider drops an API, Python developers build a wrapper within days. The feedback loop between model providers, framework authors, and application developers is tighter in Python than anywhere else — which is why the agent ecosystem moves so fast, and so chaotically.
The Four Giants: LangChain, LlamaIndex, CrewAI, AutoGen
Understanding where each framework sits helps you choose the right boundary for your project.
LangChain and LangGraph
LangChain, now with its LangGraph extension, is the most general-purpose framework. It provides abstractions for models, prompts, tools, retrievers, and memory — all composable into directed graphs. If you need to build something non-standard — a research agent with custom planning loops, a graph-based workflow with conditional branching — LangGraph gives you the graph primitives to express it.
The tradeoff is complexity. LangChain’s abstraction layers can obscure what is actually happening in your agent’s execution. Debugging a LangGraph agent requires understanding the graph state machine, the tool calling protocol, and the underlying model’s token budget simultaneously.
from langgraph.prebuilt import create_react_agent
from langchain_ollama import ChatOllama
llm = ChatOllama(model="llama3.2")
agent = create_react_agent(llm, tools=[search_wikipedia, calculate])
result = agent.invoke({"messages": [{"role": "user", "content": "Who wrote Hamlet?"}]})LlamaIndex
LlamaIndex started as a retrieval engine — connecting language models to external data sources — and grew outward into a full agent framework. Its strength remains the query and retrieval layer: if your agent’s core job is to answer questions about a document corpus, LlamaIndex’s index strategies (vector, keyword, hybrid) and query engines are the most refined option available.
In 2026, LlamaIndex’s agent capabilities are production-grade, but the framework still carries its retrieval DNA. Agents are built around query engines with tool augmentation, not the other way around.
CrewAI
CrewAI frames agents as roles in a crew. You define Agents with goals, backstories, and tools, then assign them tasks in a sequential or hierarchical process. The mental model is clean: a researcher agent, a writer agent, an editor agent — each doing their job and passing output to the next. This makes CrewAI the fastest framework to onboard non-engineers to agent concepts.
The limitation is flexibility. CrewAI’s role-task abstraction maps well to linear pipelines but breaks down when agents need to negotiate, share memory dynamically, or handle non-deterministic task graphs. For straightforward “assign roles, run pipeline” use cases, CrewAI ships faster than any alternative.
from crewai import Agent, Task, Crew
researcher = Agent(
role="Research Analyst",
goal="Find the most cited papers on RLHF",
backstory="PhD in Machine Learning, 10 years in academic research",
tools=[search_arxiv, scrape_pdf]
)
task = Task(
description="Find top 5 RLHF papers by citation count",
agent=researcher,
expected_output="List of paper titles with citations and links"
)
crew = Crew(agents=[researcher], tasks=[task])
result = crew.kickoff()Microsoft AutoGen and AG2
Microsoft retired AutoGen in late 2025 and replaced it with the new Microsoft Agent Framework. The original AutoGen open-source project lives on as AG2 (ag2.ai), maintained by the community of original contributors. Both AG2 and the new Microsoft Agent Framework continue the multi-agent conversation patterns that made AutoGen popular — coding agents, review agents, and test agents talking through a problem together.
The model-agnostic design means you can swap GPT-4 for Claude or a local model without changing the agent code. AG2 also has solid Microsoft Teams and Outlook integrations, making it a practical choice for enterprise automation inside the Microsoft ecosystem.
New Lightweight Frameworks That Gained Traction in Q1 2026
The second-generation frameworks that emerged in late 2024 reached production maturity in Q1 2026. They share a common philosophy: strip the abstraction to the minimum required to ship a working agent, then stop.
Pydantic AI
Pydantic AI is the breakout framework of 2025-2026. Built by the same team whose Pydantic library powers the OpenAI SDK, Google ADK, and Anthropic’s SDK, it brings Pydantic’s validation-first philosophy to agent development. Agents are defined as structured Pydantic models. Tool outputs are validated. LLM responses are parsed into typed objects. The result is an agent framework where runtime errors from bad data cost you less.
from pydantic_ai import Agent, RunContext
from pydantic import BaseModel
class SearchResult(BaseModel):
title: str
url: str
snippet: str
search_agent = Agent(
'anthropic:claude-sonnet-4-20250514',
result_type=SearchResult,
system_prompt="You are a research assistant. Find relevant URLs and summaries."
)
result = search_agent.run_sync("Latest developments in MCP protocol")Pydantic AI’s inspector tool gives you a local web UI showing every tool call, LLM response, and token count in real time — valuable for debugging agent loops that would otherwise be opaque.
OpenAI Agents SDK
OpenAI’s Agents SDK, released in March 2025, has accumulated over 26,000 GitHub stars and millions of monthly downloads as of early 2026. It takes a tool-use-first approach where agents are defined around the tools they can call. The SDK is deliberately minimal — handoffs, guardrails, and traced execution are the three primitives it builds on.
The SDK integrates directly with OpenAI’s trace platform, which gives you production observability out of the box. If you are building on OpenAI models and need the fastest path from prototype to monitored production, the Agents SDK is the pragmatic choice.
from agents import Agent, function_tool
@function_tool
def get_weather(city: str) -> str:
return f"Weather in {city}: sunny, 22C"
agent = Agent(
name="Travel Assistant",
instructions="Help users plan trips. Use tools to get real data.",
tools=[get_weather]
)
result = agent.run("What's the weather in Tokyo?")Smolagents (Hugging Face)
Smolagents is Hugging Face’s answer to the complexity tax. Released in late 2024, the framework is deliberately barebones — agents write Python code to call tools and orchestrate other agents. There is no graph abstraction, no state machine, no retrieval layer. If you want those things, you build them yourself.
The appeal of Smolagents is its low floor for simple agents and its transparency. When a smolagent calls a tool, you can read the actual Python code it generated and executed. For learning and debugging, this is refreshing compared to LangChain’s opaque abstraction stacks.
from smolagents import CodeAgent, HTTPTool
search = HTTPTool(
name="web_search",
url="https://api.search.example.com/search",
method="POST"
)
agent = CodeAgent(tools=[search], model_provider="anthropic")
agent.run("Find the Python 3.13 release date")Google Agent Development Kit (ADK)
Google’s ADK positions itself as the engineering-first agent framework. Where CrewAI optimizes for non-engineer onboarding, ADK expects you to understand async Python, tool schemas, and session management. The payoff is a modular, testable agent architecture — ADK agents are just Python classes with method decorators, making them natural to unit test with pytest mocks.
ADK also has first-class support for Gemini 2.0’s function calling format, which matters if you are building on Google Cloud. For Python developers who want LangGraph-level flexibility with better testability, ADK is worth the steeper learning curve.
Building a Python MCP Server
The Model Context Protocol (MCP) is the emerging standard for connecting AI applications to external tools and data. An MCP server exposes resources, tools, and prompts to any MCP-compatible host — Claude Desktop, Cursor, Windsurf, or a custom agent runtime. Unlike REST APIs where you hand-craft every endpoint, MCP defines a protocol so that a single server can serve multiple host applications without custom integration code.
Python has two paths to building an MCP server: the official MCP Python SDK and FastMCP from PrefectHQ. The SDK is lower-level; FastMCP adds the decorator-based ergonomics that Python developers expect.
Minimal MCP Server with the Official SDK
# server.py
from mcp.server import Server
from mcp.types import Tool, TextContent
from mcp.server.stdio import stdio_server
import asyncio
server = Server("python-mcp-demo")
@server.list_tools()
async def list_tools() -> list[Tool]:
return [
Tool(
name="calculate_bmi",
description="Calculate BMI from height (cm) and weight (kg)",
inputSchema={
"type": "object",
"properties": {
"height_cm": {"type": "number"},
"weight_kg": {"type": "number"}
},
"required": ["height_cm", "weight_kg"]
}
)
]
@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
if name == "calculate_bmi":
h = arguments["height_cm"] / 100 # convert to meters
bmi = arguments["weight_kg"] / (h ** 2)
return [TextContent(type="text", text=f"BMI = {bmi:.1f}")]
raise ValueError(f"Unknown tool: {name}")
async def main():
async with stdio_server() as (read_stream, write_stream):
await server.run(read_stream, write_stream, server.create_initialization_options())
if __name__ == "__main__":
asyncio.run(main())The Same Server with FastMCP
# fast_server.py
from fastmcp import FastMCP
mcp = FastMCP("python-mcp-demo")
@mcp.tool()
def calculate_bmi(height_cm: float, weight_kg: float) -> str:
"""Calculate BMI from height in cm and weight in kg."""
h = height_cm / 100
bmi = weight_kg / (h ** 2)
return f"BMI = {bmi:.1f} (category: {'healthy' if 18.5 <= bmi str:
"""Return a patient's BMI history (mock data)."""
return f"Patient {patient_id}: last recorded BMI 23.4, trend: stable"
if __name__ == "__main__":
mcp.run()FastMCP’s decorator-based approach is cleaner for most use cases. The SDK approach is preferable when you need full control over the JSON-RPC message handling or are building a server that participates in complex multi-turn tool interactions with state.
Note: MCP servers communicate over stdio (standard input/output) by default — this makes them easy to embed in any host application without network configuration. For production deployment with multiple clients, FastMCP also supports HTTP/SSE transport modes.
Connecting an MCP Server to a Python Agent
Once your MCP server is running, you can connect to it from Pydantic AI or any framework that supports MCP tool calls:
# client_example.py — connecting Pydantic AI to an MCP server
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServer
# Register the MCP server as a tool provider
mcp_server = MCPServer(
command="python",
args=["/path/to/fast_server.py"], # path to your FastMCP server
env={"LOG_LEVEL": "debug"}
)
agent = Agent(
'anthropic:claude-sonnet-4-20250514',
tools=[mcp_server] # MCP server tools become available to the agent
)
result = agent.run_sync("A patient with height 175cm and weight 70kg — what's their BMI?")Patterns for Multi-Agent Systems
A single agent that does everything is easier to write but harder to debug, scale, and maintain. Multi-agent systems decompose a complex task into specialized roles that communicate through a defined protocol. In 2026, four patterns dominate: supervisor, peer-to-peer, hierarchical, and swarm.
Supervisor Pattern — One Agent Orchestrates Many
The supervisor pattern uses a central orchestrator agent that assigns sub-tasks to specialized agents and synthesizes their results. The supervisor holds the high-level goal; it decides which specialist to call, handles their outputs, and decides when the task is complete.
# supervisor_pattern.py
from pydantic_ai import Agent
research_agent = Agent('anthropic:claude-sonnet-4-20250514', name="researcher")
writer_agent = Agent('anthropic:claude-sonnet-4-20250514', name="writer")
editor_agent = Agent('anthropic:claude-sonnet-4-20250514', name="editor")
async def run_supervisor(topic: str) -> str:
# Supervisor plans and delegates
research_task = await research_agent.run(
f"Research the latest developments in {topic}. Return key facts and sources."
)
write_task = await writer_agent.run(
f"Write a 300-word summary based on this research:n{research_task.data}"
)
edit_task = await editor_agent.run(
f"Edit this summary for clarity and brevity:n{write_task.data}"
)
return edit_task.data
import asyncio
result = asyncio.run(run_supervisor("Model Context Protocol"))
print(result)Peer-to-Peer Pattern — Agents Negotiate
In peer-to-peer multi-agent systems, agents are equals that share a message board or blackboard. Each agent monitors the shared state, picks up tasks it can handle, and posts results back. No single orchestrator decides who does what — coordination emerges from the protocol.
# blackboard_pattern.py
import asyncio
from dataclasses import dataclass
from typing import Optional
@dataclass
class BlackboardMessage:
sender: str
content: str
task_type: str # "research", "code", "review"
class Agent:
def __init__(self, name: str, task_types: list[str], board: list[BlackboardMessage]):
self.name = name
self.task_types = task_types
self.board = board
async def poll(self):
for msg in self.board:
if msg.task_type in self.task_types:
# Process the task
result = f"{self.name} processed: {msg.content[:50]}"
self.board.append(BlackboardMessage(self.name, result, "done"))
break
# Two agents sharing a blackboard
board: list[BlackboardMessage] = []
researcher = Agent("Researcher", ["research"], board)
coder = Agent("Coder", ["code"], board)
board.append(BlackboardMessage("user", "Analyze MCP Python SDK and write a benchmark", "research"))
await researcher.poll()
await coder.poll()
print([m.content for m in board if m.task_type == "done"])Hierarchical Pattern — Teams Under Supervisors
The hierarchical pattern extends the supervisor pattern with multiple levels. A lead agent decomposes a complex goal into team goals, assigns each to a supervisor, and those supervisors manage their own specialist agents. This mirrors how human organizations work — and scales to complex enterprise tasks.
# hierarchical_agents.py
from pydantic_ai import Agent
# Specialist agents
code_agent = Agent('anthropic:claude-sonnet-4-20250514', name="code_specialist")
test_agent = Agent('anthropic:claude-sonnet-4-20250514', name="test_specialist")
deploy_agent = Agent('anthropic:claude-sonnet-4-20250514', name="deploy_specialist")
# Team supervisor
dev_supervisor = Agent(
'anthropic:claude-sonnet-4-20250514',
name="dev_supervisor",
system_prompt="You manage a development team. Delegate coding, testing, and deployment tasks."
)
# Lead orchestrator
lead = Agent(
'anthropic:claude-sonnet-4-20250514',
name="lead",
system_prompt="A customer requested a new feature. Break it down and coordinate delivery."
)
# The lead delegates to team supervisors; supervisors manage specialists
# In practice, use LangGraph's StateGraph for production-grade hierarchical control flowTool Use and Memory in Multi-Agent Systems
Three problems appear the moment you move from single-agent to multi-agent: tool naming conflicts, shared memory, and output verification. The solutions are architectural, not just code-level.
Tool Use Across Agent Boundaries
When multiple agents expose tools with the same name (e.g., `search` appears in a research agent and a web crawler agent), the calling context must qualify the tool. Prefix tool names by domain: `research.search`, `crawler.search`. In Pydantic AI, use the `Tool` class to define namespaced tools properly.
# Tool namespacing prevents conflicts in multi-agent systems
from pydantic_ai import Agent
from pydantic_ai.tools import Tool
researcher = Agent(
'anthropic:claude-sonnet-4-20250514',
name="researcher",
tools=[Tool(name="research.search", description="Search academic papers")]
)
crawler = Agent(
'anthropic:claude-sonnet-4-20250514',
name="crawler",
tools=[Tool(name="crawler.search", description="Search web pages")]
)
# Supervisor can call both without ambiguity
supervisor = Agent('anthropic:claude-sonnet-4-20250514', name="supervisor")
# Calls: researcher.research.search(query="MCP protocol"), crawler.crawler.search(url="...")Shared Memory Across Agents
Agent memory in 2026 has two layers: short-term working memory (conversation context) and long-term episodic memory (learned facts across sessions). For multi-agent systems, the practical solution is a shared vector store or key-value memory service that all agents can read and write.
# Shared memory across agents using an in-memory store
from pydantic import BaseModel
from typing import Optional
import time
class MemoryEntry(BaseModel):
key: str
value: str
agent: str
timestamp: float
class SharedMemory:
def __init__(self):
self.store: dict[str, MemoryEntry] = {}
def write(self, key: str, value: str, agent: str):
self.store[key] = MemoryEntry(key=key, value=value, agent=agent, timestamp=time.time())
def read(self, key: str) -> Optional[str]:
entry = self.store.get(key)
if entry:
return f"[{entry.agent} @ {entry.timestamp}]: {entry.value}"
return None
def recent(self, n: int = 5) -> list[MemoryEntry]:
return sorted(self.store.values(), key=lambda e: e.timestamp, reverse=True)[:n]
# Agents share the same memory instance
memory = SharedMemory()
def researcher_agent(task: str):
result = f"Researched: {task}"
memory.write(f"task_{task[:20]}", result, "researcher")
return result
def writer_agent():
recent = memory.recent(3)
return [f"{e.key}: {e.value}" for e in recent]
researcher_agent("Model Context Protocol adoption rates")
writer_agent()For production deployments, swap the in-memory store for Redis with a vector similarity index — this gives you both fast key-value access and semantic retrieval across agent sessions.
Common Mistakes with AI Agents in Python
- Tool explosion — giving an agent 40 tools causes decision paralysis. Keep tools narrow and composable. If a tool does two things, split it.
- Missing output validation — LLMs return unstructured text. Without Pydantic validation or JSON schema enforcement, bad tool outputs propagate silently through the agent loop.
- Memory leaks in long-running agents — conversation history grows unbounded. Implement truncation or summarization after every N turns.
- Synchronous tool calls blocking the event loop — if your agent runs in an async context, ensure all tool implementations are non-blocking or run on a thread pool.
- Single-agent overengineering — building a multi-agent orchestration for a simple task adds latency and complexity. Start with one agent, decompose only when you hit a clear boundary.
Summary and Next Steps
Python’s dominance in the AI agent ecosystem comes from its flexibility, the speed of its feedback loop between providers and developers, and the depth of its data-processing stack. In early 2026, the framework landscape is bifurcating: the large orchestration frameworks (LangGraph, AG2) handle complex enterprise workflows, while lightweight frameworks (Pydantic AI, OpenAI Agents SDK, smolagents, Google ADK) are winning the prototype-to-production segment with minimal abstractions.
The Model Context Protocol is the most significant infrastructure development for Python agent developers in years — it standardizes the tool and data integration layer that previously required custom glue code for every deployment. Invest time in understanding MCP servers and clients; the pattern will outlive any individual framework.
Start with these articles on PyBlog:
- Python Functions: The Complete 2026 Guide — foundational for understanding agent tool schemas
- Python Async/Await: Complete Guide — required knowledge for production async agents
- Python Type Hints: Complete Guide — apply type safety to agent tool definitions
