█████╗ ██╗     █████╗  ██████╗ ███████╗███╗   ██╗████████╗███████╗
██╔══██╗██║    ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝██╔════╝
███████║██║    ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ███████╗
██╔══██║██║    ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ╚════██║
██║  ██║██║    ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ███████║
╚═╝  ╚═╝╚═╝    ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝

AI Agents — Multi-Provider Developer Guide

Focus: How to build AI agents across the four stacks you'll actually reach for — xAI Grok, Anthropic (Claude Agent SDK), Microsoft (Agent Framework + Copilot agent mode), and Google (ADK + Agent Engine) — their scope and capabilities, how to wire tools, and the MCP connector that links them all. Grounded in each vendor's official docs; reviewed 2026-06-07.

What an agent actually is

Strip away the hype: an agent is a language model put in a loop with tools. It reads the goal, decides whether it can answer directly or needs a tool, calls the tool, reads the result, and loops — until it can give a final answer. That's it. Everything else (memory, multi-agent, hosting) is built on top.

The two non-negotiables: tools (what the agent can do — search, query a DB, send an SMS) and stop conditions (when to quit the loop). Get those right and the rest is plumbing.

Official Documentation

MCP — the universal connector

Before the providers, learn the thing that ties them together. MCP (Model Context Protocol) is an open standard: an MCP server exposes tools, resources, and prompts; any MCP-capable agent (client) can consume them over stdio (local subprocess) or HTTP. Build your "send M-Pesa receipt" or "query Supabase" tool once as an MCP server, and every agent below can call it.

Every provider in this guide speaks MCP — that's the bet: write tools once, reuse everywhere. See the github and supabase guides for first-party MCP servers you can attach today.

1. xAI — Grok agents

• Scope: frontier reasoning + a strong server-side agentic toolset (the model runs the tool loop for you). OpenAI-API-compatible, so it drops into existing OpenAI code too.
• Install & a client-side tool (you run the tool):

# pip install xai-sdk   (Python 3.10+)
import json
from pydantic import BaseModel, Field
from xai_sdk import Client
from xai_sdk.chat import system, user, tool, tool_result

client = Client()  # reads XAI_API_KEY

class WeatherReq(BaseModel):
    city: str = Field(description="City name")

def get_weather(city: str) -> str:
    return f"Sunny, 26°C in {city}"

chat = client.chat.create(
    model="grok-4",  # check docs.x.ai for the current model id
    messages=[system("You are a helpful assistant.")],
    tools=[tool(name="get_weather", description="Current weather for a city.",
                parameters=WeatherReq.model_json_schema())],
)
chat.append(user("Weather in Nairobi?"))
resp = chat.sample()
chat.append(resp)
for tc in resp.tool_calls:                      # the model asked to call a tool
    args = json.loads(tc.function.arguments)
    chat.append(tool_result(get_weather(**args), tool_call_id=tc.id))
print(chat.sample().content)                     # final answer after the tool result

• Server-side / MCP tools (xAI runs the loop): pass web_search(), x_search(), code_execution(), collections_search(), or mcp(server_url=..., authorization="Bearer …") into tools= and the model autonomously searches, runs code, or calls your remote MCP server.

from xai_sdk.tools import web_search, code_execution, mcp
chat = client.chat.create(model="grok-4", tools=[
    web_search(), code_execution(),
    mcp(server_url="https://mcp.example.com", authorization="Bearer TOKEN"),
])

• Gotcha: client-side tools support up to 128 per request; you own the execution + the loop. Server-side tools are billed per use and run inside xAI. Keep XAI_API_KEY server-side.

2. Anthropic — Claude Agent SDK

• Scope: the production-grade agent harness behind Claude Code — file/bash/web tools, hooks, permissions, subagents, and first-class MCP. Best when you want a capable coding/ops agent with strong guardrails.
• Install & a custom tool exposed over an in-process MCP server:

# pip install claude-agent-sdk   (also: npm i @anthropic-ai/claude-agent-sdk)
from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, query

@tool("mpesa_status", "Check an M-Pesa STK payment status", {"checkout_id": str})
async def mpesa_status(args):
    status = await lookup(args["checkout_id"])  # your code
    return {"content": [{"type": "text", "text": status}]}

server = create_sdk_mcp_server(name="mpesa", version="1.0.0", tools=[mpesa_status])

options = ClaudeAgentOptions(
    mcp_servers={"mpesa": server},
    allowed_tools=["mcp__mpesa__mpesa_status"],   # pre-approve → no permission prompt
)

async for msg in query(prompt="Is checkout ws_CO_123 paid?", options=options):
    print(msg)

• MCP wiring: tools are addressed as mcp__{server}__{tool}. allowed_tools pre-approves a tool (skips the human prompt) — it does not control availability. Use ClaudeSDKClient instead of query() for multi-turn, bidirectional sessions.
• Gotcha: allowed_tools is a permission allowlist, not a feature flag — be deliberate about what runs unattended (especially bash/write). Set ANTHROPIC_API_KEY server-side. See anthropic for models + prompt caching.

3. Microsoft — Agent Framework + Copilot agent mode

Two complementary surfaces.

a) Build agents in code — Microsoft Agent Framework

The unified successor to Semantic Kernel + AutoGen (same teams), public preview in C# and Python, with session state, middleware/telemetry, graph-based multi-agent workflows, and MCP support.

# pip install agent-framework   (preview)
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient   # or Azure AI Foundry, etc.

agent = Agent(
    client=OpenAIChatClient(),                 # any IChatClient-style provider
    instructions="You are codeAmani's Swahili-fluent support agent.",
    tools=[get_weather],                       # plain functions become tools
)
result = await agent.run("Habari ya hali ya hewa Nairobi?")
print(result)

In .NET the base type is AIAgent and a single ChatClientAgent wraps any IChatClient provider. The framework also ships CopilotStudioAgent and an A2AAgent (agent-to-agent).

b) Drive an agent in the IDE — Copilot agent mode

In VS Code / Visual Studio, open Chat → switch to Agent mode → the tools icon lists available tools, including any MCP servers you've added. Reference a tool inline with #tool_name. This is how you wire MCP servers (Microsoft Learn, Azure, your own) into the editor agent.

// .vscode/mcp.json — add an MCP server to Copilot agent mode
{ "servers": { "mpesa": { "command": "npx", "args": ["-y", "mpesa-mcp"] } } }

• Gotcha: Agent Framework is preview — APIs may shift; pin versions. Treat IDE agent tools like production access: require approval for file writes / shell.

4. Google — Agent Development Kit (ADK)

• Scope: an open, code-first agent toolkit, Gemini-optimised but model-agnostic, that deploys cleanly to Vertex AI Agent Engine (managed sessions + Memory Bank — see google-cloud).
• Install & a tool agent:

# pip install google-adk
from google.adk.agents import Agent
from google.adk.runners import InMemoryRunner
from google.genai import types

def get_weather(city: str) -> dict:
    """Current weather for a city.  (the docstring is the tool's description)"""
    return {"status": "success", "report": f"Sunny, 26°C in {city}"}

agent = Agent(
    name="weather_agent",
    model="gemini-flash-latest",
    instruction="Use the tools to answer.",
    tools=[get_weather],          # plain Python functions; docstring matters
)

runner = InMemoryRunner(agent=agent, app_name="weather")
# runner.run_async(user_id=..., session_id=..., new_message=types.Content(...))

• MCP wiring: attach servers with McpToolset(connection_params=StdioConnectionParams(...)) (or SseConnectionParams for remote), with an optional tool_filter.
• Deploy: export GOOGLE_GENAI_USE_VERTEXAI=TRUE to run on Vertex; push to Agent Engine for managed hosting + memory.
• Gotcha: ADK reads your function's docstring + type hints as the tool schema — write them well. Region-pin for data residency (KDPA).

Choosing a provider

Rule of thumb for codeAmani: Claude Agent SDK for ops/coding agents with strong guardrails; Google ADK when you're already on GCP/Gemini and want managed Agent Engine memory; Grok for live-web/X research; Microsoft when the stack is .NET/Azure or you want the in-IDE Copilot agent.

Capabilities & scope (what to expect)

• Tools — the agent's hands. Anything you can call from code can be a tool (HTTP, DB, M-Pesa, SMS). Keep each tool small, typed, and documented.
• Memory & state — short-term (the conversation) vs long-term (Agent Engine Memory Bank, a vector store — see pinecone/pgvector).
• Multi-agent — split work across specialised agents (planner → workers → reviewer). All four support it; Microsoft's graph workflows make the control flow explicit.
• Human-in-the-loop — gate risky actions behind approval. Non-negotiable for anything that moves money or writes to prod.
• What agents are bad at — unbounded loops (set step/turn limits + budgets), and silent failure (log every tool call + result).

codeAmani notes

• Secrets stay server-side. Model keys (XAI_API_KEY, ANTHROPIC_API_KEY, Google ADC, Azure creds) and tool credentials live in env/secret managers (infisical), never in client code or prompts. MCP servers that touch money or PII run server-side only.
• Allowlist + approve. Pre-approve only safe, read-only tools for unattended runs; require human approval before any agent action that triggers an M-Pesa transfer, deletes data, or deploys. Treat allowed_tools / IDE agent tools as production access.
• Bound the loop. Cap turns/steps and set a token/cost budget — an agent in a tool loop can burn spend fast. Log every tool call + result for audit.
• AI routing. Reuse the house policy: complex reasoning/coding → Claude; GCP/Gemini-native + managed memory → Google ADK/Agent Engine; live web/X research → Grok; structured/function-calling-heavy flows → whichever SDK fits the runtime. Build shared tools as MCP servers so the choice of agent stays swappable.
• African market. A Swahili-fluent support agent with an mpesa MCP tool (check status, send receipt) is a high-leverage first build — keep the callback + reconciliation idempotent (see daraja + webhooks), and region-pin hosted agents (africa-south1 / europe-west1) for latency + residency.