Build, operate, and debug
with confidence.

Overview

What the mAIvn SDK is, the one mental model behind it, and where to start.

Getting Started

Install the SDK and run your first agent invocation.

Core Concepts

Agents, swarms, tools, dependency-aware execution, and sessions in one place.

Tools

Define function tools and model tools with the right execution boundaries.

Dependencies

Model tool and agent dependencies for reliable execution graphs.

Structured Output

Guarantee typed responses with schema-driven output patterns.

Multi-Agent

Coordinate specialized agents using Swarm workflows.

Sessions, Streaming & ModelConfig

How invoke and stream relate, sync versus async, ModelConfig, live available models, and what a session response carries.

System Tools

Understand built-in web search, code execution, and reasoning tools.

Private Data and PII

Keep secrets and PII out of the model: schema-only planning, execution-time injection, and RedactedMessage for automatic detection and redaction.

Interrupts & Human-in-the-Loop

Pause an agent for human input mid-run and resume the session safely.

Frontend Events

Stream live execution events from your mAIvn backend to any frontend with a one-line FastAPI mount and a browser EventSource example.

Connecting MCP Servers

Connect external Model Context Protocol tool servers to your agents.

Memory and Recall

Configure summarize, retrieval, and async indexing for long-running threads.

Scheduled Invocation

Run agents and swarms on cron, interval, or one-shot schedules with built-in retries, jitter, and lifecycle controls.

Timeouts, Retries & Reliability

Bound calls with timeouts and retry transient failures gracefully.

Authentication & API Keys

How the SDK authenticates, key scopes from the consumer's point of view, and rotating keys without downtime.

SDK Resource Management

Manage project resources and organization memory settings programmatically.

Testing & Local Development

Test agents and tools without hitting the live orchestrator.

Examples Overview

Index of runnable example pages, organized by what you'd want to build.

Basics

A first agent. Function and Pydantic tools. Tool chaining. Private data injection. Structured final output.

Agents & Tools

Three ways to register tools, cross-agent dependencies, before/after hooks, and datetime awareness.

Swarms

Multi-agent collaboration with designated final-output agents, per-agent final tools, and member-style registration.

MCP Integration

Registering MCP servers over stdio and HTTP, including auto-setup for third-party servers.

Memory

Memory configuration, retrieval policies, skill and insight extraction, attaching resources.

Private Data

Inject server-side secrets without exposing them to the model, placeholder replacement, and RedactedMessage.

Batch & Scheduling

agent.batch and agent.cron / every / at. Retry, jitter, and overlap policies for production schedules.

Interrupts

Human-in-the-loop input collection with @depends_on_interrupt, including custom web handlers.

Real-World Projects

Larger end-to-end examples: automobile spec, data harmonization, HTML email builder, financial planner with MCP.

Tools Overview

The official connector layer for the mAIvn SDK: a connector kernel, generic adapters, and ready-made provider toolsets.

Quickstart

The shortest path from pip install to a working tool on an Agent.

Writing Your Own Toolset

Build toolsets with the @toolset / @toolify decorators and register them with add_toolset.

Architecture

How the connector kernel layers fit together and where to extend.

Auth & Secrets

Auth strategies, secret resolvers, and credential safety.

HTTP Runtime

Transport, retries, rate limits, pagination, and error normalization.

Generic Adapters

Turn HTTP, OpenAPI, GraphQL, webhooks, and MCP servers into tools without per-provider glue.

Files & Attachments

MIME detection, attachments, extractors, and bulk transfers.

Events & Audit

Audit events, sinks, and webhook signature verification.

Testing Connectors

Use MockTransport and fixtures to test connectors without live providers.

Permissions & Dry-run

Permission flags, destructive markers, and the dry-run contract.

API Policy

Stable surface, semantic versioning, and the deprecation policy.

Security Policy

Credential handling, destructive actions, webhook signing, and path safety.

Storage

LocalFiles, Box, and Dropbox toolsets.

Email (IMAP/SMTP)

IMAP and SMTP toolsets.

Email Delivery

Resend, SendGrid, Mailgun, Postmark, Amazon SES, and other ESP toolsets.

Google Workspace

Gmail, Google Calendar, and Google Drive toolsets.

Microsoft Graph

Outlook Mail, Outlook Calendar, and Microsoft Files toolsets.

Google Productivity

Google Docs, Sheets, and Slides toolsets.

Microsoft Productivity

Microsoft Excel, Word, and PowerPoint toolsets.

Knowledge Bases & No-Code

Notion, Confluence, and Airtable toolsets.

Collaboration & Messaging

Slack, Microsoft Teams, Google Chat, and Zoom toolsets.

Social Media

X, Meta, Instagram, LinkedIn, TikTok, YouTube, and other social toolsets.

Developer Platforms

GitHub, GitLab, Bitbucket, and Azure DevOps toolsets.

Project Management

Jira and Linear toolsets.

Support & ITSM

Zendesk and ServiceNow toolsets.

CRM

HubSpot and Salesforce toolsets.

Databases

SQLite, Postgres, MySQL, SQL Server, and Supabase toolsets.

Warehouses

Snowflake and BigQuery toolsets.

ETL & Data Movement

Fivetran, Airbyte, dbt Cloud, Hightouch, Census, and Stitch toolsets.

Analytics & BI

Amplitude, Mixpanel, Segment, PostHog, Looker, Tableau, and other analytics toolsets.

HR & People Ops

Workday, BambooHR, Rippling, Gusto, Greenhouse, Lever, and Deel toolsets.

Marketing & Ads

Marketo, Iterable, Braze, Google Ads, Meta Ads, and other marketing toolsets.

Payments & Finance

Stripe, Square, PayPal, Plaid, QuickBooks, Xero, and other finance toolsets.

E-commerce

Shopify, WooCommerce, BigCommerce, Magento, Amazon Seller, and other commerce toolsets.

Trading & Market Data

Alpaca, Polygon, Coinbase, Kraken, Binance, and other trading toolsets.

AI Providers

OpenAI, Anthropic, Gemini, Bedrock, Mistral, Cohere, and other AI-provider toolsets.

Vector Stores

Pinecone, Weaviate, Qdrant, Chroma, and Milvus toolsets.

Cloud & Observability

Datadog, Sentry, PagerDuty, New Relic, Splunk, Grafana, and other ops toolsets.

AWS Core

Amazon S3, Lambda, CloudWatch Logs, and IAM toolsets.

Identity & Security

Auth0, Okta, Vault, 1Password, Bitwarden, Snyk, Twilio, and other identity toolsets.

Partner Hubs

Workato, Pipedream, Make, n8n, Composio, and the Zapier connector.

Portal Authentication

Configure sign-in and resolve common login issues in the developer portal.

Organization and Project Operations

Manage organizations, projects, and current navigation defaults.

API Keys and Webhooks

Operate key lifecycle and webhook delivery with production safeguards.

Portal Memory Management

Configure org memory policy and curate project skills, insights, and resources.

Billing and Usage

Understand subscription, usage thresholds, and invoice workflows.

mAIvn Studio

Run Studio with default config, execute apps, and inspect live SSE execution events.

Studio Authoring and Debugging

Author Studio-ready apps, use runtime patch APIs, and debug sessions efficiently.

API Overview

Top-level SDK API map and import surface.

Agent

Core Agent class constructor, methods, and usage patterns.

Swarm

Swarm orchestration API for coordinating multi-agent systems.

Client

HTTP client lifecycle and connection reuse behavior.

Decorators

Dependency decorators for tools, agents, data, and interrupts.

Events

Public event models, builders, bridge audiences, and stream normalization helpers for frontend integrations.

Configuration

Configuration model hierarchy and environment overrides.

Session Config Models

Typed invocation config objects for memory, system tools, orchestration, structured output, and swarm transport.

MCP

Model Context Protocol integration, local execution boundaries, and stdio environment hardening controls.

Messages

Message types and semantics used across invocations.

Logging

SDK logging hooks, file output, and diagnostics patterns.

Scheduling

Cron, interval, and at-time schedules with retry, jitter, and process-wide job registry helpers.

Billing & Usage

Read your organization's plan, usage-vs-limits, and the org -> project -> API-key usage breakdown via Client.get_usage().

Data Models

The typed shapes you read off responses and pass in - SessionResponse, RawSSEEvent, TokenUsage, the privacy models, and billing/usage models.

Errors & Exceptions

The SDK error model: the MaivnError base, the validation/execution/transport failure layers, and how to catch and handle each.

Best Practices

Production-grade patterns for robust agent behavior.

Troubleshooting

Common failure modes and practical resolution steps.

Versioning & Stability

What the SDK version and event-contract version mean, which surfaces are stable, and how deprecations are communicated.

Glossary

Plain-language definitions of the core mAIvn terms - agents, swarms, tools, dependencies, sessions, and more.