smolagents

• What smolagents ships — the agent loop (CodeAgent, ToolCallingAgent), sandboxed code execution, model-agnostic backends (InferenceClientModel, OpenAIServerModel, LiteLLMModel, …), multi-agent orchestration, and MCP clients over stdio, streamable-http, and sse — including auth headers on remote servers.
• What it doesn’t ship — a way for those agents to act as a real account: sign up for a SaaS tool, hold a funded card, or spend within a budget you control, per end-user.

​

How the pairing works

• smolagents turns any MCP server into a set of tools: ToolCollection.from_mcp(...) connects, discovers the server’s tools, and hands them to your agent — no manual schema wiring.
• Naive ships a hosted MCP server and mints per-user sessions — short-lived, revocable SSE endpoints whose tool list is the fused native + third-party toolset, already filtered by that user’s Account Kit.
• Each session is one URL + one bearer scoped to one user. Load it as a ToolCollection, spread its tools into a CodeAgent, and every tool call runs as that user — gated server-side.

  smolagents (CodeAgent)                 Naive
  ──────────────────────                 ─────
  model writes Python ── tool call ─────▶ loop
    │  code calls a Naive tool
    ▼
  ToolCollection.from_mcp (SSE + bearer) ▶  /mcp/sse/sess_…   (per-user session)
                                            │  AccountKit-gated, scoped to one user
                                            ▼
                                      connect GitHub · issue a $50 card · run a capability
                                            │
                                      sensitive? → 202 pending_approval (human-in-the-loop)

​

Prerequisites

• A Naive API key (nv_sk_...) — get one from the dashboard.
• A model provider key for the LLM that runs the agent (e.g. OPENAI_API_KEY, or a HF_TOKEN for InferenceClientModel).
• Python ≥ 3.10.

pip install "smolagents[mcp,openai]" httpx

export NAIVE_API_KEY=nv_sk_live_...
export OPENAI_API_KEY=sk-...

​

Minimal viable integration

# Control plane: a reusable policy template.
curl -X POST https://api.usenaive.ai/v1/account-kits \
  -H "Authorization: Bearer $NAIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro",
    "primitives_config": {
      "cards": { "enabled": true, "requiresApproval": true, "defaults": { "spending_limit_cents": 50000 } },
      "vault": { "enabled": true }
    },
    "connections_config": { "mode": "allowlist", "toolkits": ["github", "gmail", "stripe"] }
  }'
# → { "id": "<kit_id>", ... }

# Provision one of your end-users and assign the kit.
curl -X POST https://api.usenaive.ai/v1/users \
  -H "Authorization: Bearer $NAIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "user_123", "email": "alice@acme.com", "account_kit_id": "<kit_id>" }'
# → { "id": "<user_id>", ... }

import os
import httpx

NAIVE_API = "https://api.usenaive.ai"
AUTH = {"Authorization": f"Bearer {os.environ['NAIVE_API_KEY']}"}

ALICE_USER_ID = "<user_id>"  # from the control-plane step

def mint_session(user_id: str, ttl_ms: int = 15 * 60 * 1000) -> dict:
    r = httpx.post(
        f"{NAIVE_API}/v1/users/{user_id}/sessions",
        headers=AUTH,
        json={"ttl_ms": ttl_ms},
    )
    r.raise_for_status()
    return r.json()  # { id, expires_at, mcp: { url, headers, expires_at } }

from smolagents import CodeAgent, ToolCollection, OpenAIServerModel

session = mint_session(ALICE_USER_ID)

# Naive's session is SSE; the scoped bearer rides in headers — never in the URL.
server_parameters = {
    "url": session["mcp"]["url"],
    "transport": "sse",
    "headers": session["mcp"]["headers"],
}

model = OpenAIServerModel(model_id="gpt-4.1")

# from_mcp is a context manager: the connection closes on exit.
with ToolCollection.from_mcp(server_parameters, trust_remote_code=True) as tool_collection:
    agent = CodeAgent(tools=[*tool_collection.tools], model=model)
    agent.run(
        "Connect my GitHub, then issue a $50 virtual card called "
        "'Ads budget' for our marketing spend."
    )

​

Extension: human-in-the-loop spend

• In smolagents — you shape the run by narrowing which tools the agent even sees (subset tool_collection.tools, above) and by keeping code execution sandboxed.
• On the server — even if a call gets through, Naive freezes the sensitive action and returns a pending approval (HTTP 202) instead of a live card. This holds no matter what runtime calls it.

{
  "status": "pending_approval",
  "approval_id": "65589c8b-e033-4a65-b16c-379211c94429",
  "action_type": "cards.create",
  "primitive": "cards",
  "title": "Issue virtual card \"Ads budget\""
}

def list_pending(user_id: str) -> list[dict]:
    r = httpx.get(
        f"{NAIVE_API}/v1/users/{user_id}/approvals",
        headers=AUTH,
        params={"status": "pending"},
    )
    r.raise_for_status()
    return r.json()["approvals"]

def approve(user_id: str, approval_id: str) -> dict:
    r = httpx.post(
        f"{NAIVE_API}/v1/users/{user_id}/approvals/{approval_id}/approve",
        headers=AUTH,
    )
    r.raise_for_status()
    return r.json()

# Find what the agent queued for Alice, then approve (or deny) it.
for a in list_pending(ALICE_USER_ID):
    # ...show a["title"] / a["action_type"] to a human in your UI...
    approve(ALICE_USER_ID, a["id"])  # API replays cards.create → real card

​

Alternative: one agent definition, every tenant

def run_for_user(user_id: str, task: str) -> str:
    session = mint_session(user_id)  # fresh, per-user session
    server_parameters = {
        "url": session["mcp"]["url"],
        "transport": "sse",
        "headers": session["mcp"]["headers"],
    }
    model = OpenAIServerModel(model_id="gpt-4.1")

    with ToolCollection.from_mcp(server_parameters, trust_remote_code=True) as tools:
        agent = CodeAgent(tools=[*tools.tools], model=model)
        return agent.run(task)

# Same agent code, different tenant — isolated identity, spend, and approvals each time.
# run_for_user("<user_id>", "Connect GitHub and set up a $50 ads card.")

from smolagents import CodeAgent, MCPClient, OpenAIServerModel

mcp_client = MCPClient(server_parameters)
try:
    agent = CodeAgent(tools=mcp_client.get_tools(), model=OpenAIServerModel(model_id="gpt-4.1"))
    agent.run("Connect GitHub and set up a $50 ads card.")
finally:
    mcp_client.disconnect()  # always clean up the session connection

​

What stays enforced

• Identity — every action runs as a specific tenant user, fully isolated from your other users.
• Capability bounds — the Account Kit decides which primitives and which apps the agent can touch (allowlist / blocklist / per-tool).
• Scoped spend — virtual cards are capped per card and per user; the model can’t raise its own limit.
• Human-in-the-loop — sensitive actions (cards, domains, KYC, formation, connecting an app) freeze as approvals until a human says yes.
• Scoped, expiring access — the agent holds a per-user session bearer, not your API key; it expires (default 15 min) and you can DELETE /v1/users/:user_id/sessions/:id to revoke it early.

​

Next steps

• MCP server — the hosted SSE server and its full tool list
• Sessions — per-user MCP sessions, TTL, and revocation
• Account Kits — author spend/capability policy
• Approvals — the human-in-the-loop lifecycle
• Pydantic AI · LlamaIndex · Agno — the same MCP-session pairing for other Python stacks

​

Related reading (blog)

• Naïve inside your agent framework — concept map for every integration guide
• Delegated, revocable MCP sessions — session model for Python and MCP guides
• The Governed Agent Profile — caps, approvals, and revoke on every tool call
• Building AI Agents Into Your SaaS — multi-tenant architecture this pairing assumes