Examples Overview - mAIvn Docs

#Examples

A working tour of the SDK, organized by what you'd actually want to build. Each page contains runnable snippets, comments on what's load-bearing, and links back to the relevant guide for deeper coverage.

If you're brand new, start with the Quickstart: typed tool → answer model → tools=[...] → invoke(..., structured_output=Model) → response.result. Continue with Basics for more registration and dependency patterns.

#Run the existing catalog

The maivn-examples project contains 50 runnable entries with per-example instructions: 12 scenarios and 38 focused feature tutorials. Open its checkout or downloaded archive and work from the folder containing pyproject.toml, .env.example, and examples/. In the platform checkout, use cd apps/maivn-examples from the platform root. A standalone checkout or archive uses its own maivn-examples folder. Python 3.12 or newer is required.

Shell

python -m venv .venv
source .venv/bin/activate
python -m pip install .
python -m examples.assistants.quickstart.demo --help

PowerShell activates with .venv\Scripts\Activate.ps1. With uv, use uv sync and prefix module commands with uv run. Installing the project includes all declared dependencies, including the examples' python-dotenv loader.

Catalog imports and help need no key. For execution, create a runtime API key in your developer portal and set MAIVN_API_KEY in your shell or copy .env.example to .env in the examples project folder. Shell values take precedence. Then run:

Shell

python -m examples.assistants.quickstart.demo

Expect a status card for PK-1003, a customs hold, a delivery date five days from today, and validation: PASS - 5 checks. A missing key fails before dispatch; an incorrect result fails the demo's checks. The project README explains optional endpoint configuration and Studio installation. For Studio with uv, launch from that folder with uv run --extra studio python -m maivn_studio.main.

#Choose a starter and customize it

Catalog module	Start here when you need	First change
`examples.assistants.quickstart.demo`	A tool and a typed answer	Replace the parcel lookup, update an answer field and the factual checks; preserve the named `status_card` Studio selection.
`examples.features.tools.custom_toolset.demo`	Shared state with different read/write roles	Replace the fleet fixtures and review tool and agent permissions.
`examples.assistants.support_resolution.demo`	Human approval before an action	Replace the order policy and exact approval prompt; retain the boolean interrupt and one receipt per approved order.
`examples.analysis.research_desk.demo`	Specialist findings feeding a report	Replace desk research and report fields; retain both specialist dependencies and checks.

Each starter's README includes a “Make it yours” path. Update tools, answer models, prompts, and factual checks together. Identify live requests, file writes, and other effects as you introduce them. These demos use synthetic inputs unless their instructions identify a live source.

#Index

Page	What you'll learn
Basics	A first agent. Function and Pydantic tools. Tool chaining. Private data injection. Structured final output.
Agents & Tools	The three ways to register tools (`@agent.toolify`, `agent.add_tool(...)`, `Agent(..., tools=[...])`). Tool execution hooks. Cross-agent dependencies.
Swarms	Multi-agent collaboration with `Swarm`. Designated final-output agents. Member-style registration. Per-agent `final_tool` ownership.
MCP Integration	Registering MCP servers over stdio and HTTP. Auto-setup for third-party servers.
Memory	Memory configuration, retrieval policies, skill/insight extraction, attaching resources.
Decisions	Categorical answers, native batching, invocation gates and typed arguments with explicit privacy and fallback.
Private Data	`@depends_on_private_data`, referencing private values by key, `RedactedMessage`.
Batch & Scheduling	`agent.batch(...)` plus remote and explicitly local `cron(...)` / `interval(...)` scheduling.
Interrupts	Human-in-the-loop input collection with `@depends_on_interrupt`.
Real-World Projects	Larger end-to-end examples — automobile spec, data harmonization, HTML email builder, financial planner with MCP.

#How to read the examples

The snippets are condensed — boilerplate (logging setup, .env loading, argparse) is omitted so you can see the SDK surface clearly. To run them locally, all you need is:

Python

import os
from maivn import Agent
from maivn.messages import HumanMessage

agent = Agent(
    name='My Agent',
    system_prompt='...',
    api_key=os.environ['MAIVN_API_KEY'],
)

agent.invoke([HumanMessage(content='hello')])

Most examples also work inside mAIvn Studio — if you see APP_PROMPTS = [...] in the source repo, that's the Studio prompt picker metadata.

#What's missing here

These examples cover the SDK surface. For the platform (auth, billing, projects, webhooks, IAM, analytics) — see the Developer Portal guides. For Studio-specific authoring and debugging, see mAIvn Studio guide.