API Overview

#SDK Reference

The supported public SDK surface, grouped by import path and linked to the detailed reference pages.

This page is the hub. If you are building your first agent, start with the Getting Started guide and the Agent reference. Come back here when you need to find an exact name or see how the pieces fit together. This page documents the behavioral surface (how to build, invoke, and stream). For the shapes that behavior produces and consumes (InvokeResponse, its token_usage dictionary, and privacy and billing models), see Shared Data Models.

#What this is

maivn is a Python SDK for building agentic systems. You describe what your agent can do (its tools, its dependencies, its configuration) as plain Python objects, and the SDK runs each request through an orchestrator that decides what to call and when. Everything you need lives behind a single import:

from maivn import Agent
from maivn.messages import HumanMessage

agent = Agent(name='assistant', api_key='your-api-key')
response = agent.invoke([HumanMessage(content='Hello!')])
print(response.response)

The whole programming surface is the SDK. You construct Agent and Swarm objects, register tools with decorators, tune behavior with typed config models, and read results off a InvokeResponse. Tool code runs locally in your environment. The SDK sends only tool schemas (names, descriptions, parameters) for planning.

Note invoke() returns a InvokeResponse. Use response.response for the final assistant text and response.result for structured or final-tool output.

#The public import surface

The core classes, decorators, configuration, scheduling, and interrupt helpers below are exported from maivn. Event normalization and frontend-bridge APIs live in maivn.events; message types live in maivn.messages.

from maivn import (
    # Version
    __version__,

    # Core Classes
    Agent,
    Swarm,
    Client,
    ClientBuilder,
    BaseScope,
    ToolOverride,
    MCPServer,
    MCPAutoSetup,
    MCPSoftErrorHandling,

    # Decorators
    tool_output,
    toolify,
    toolset,
    depends_on_tool,
    depends_on_agent,
    depends_on_private_data,
    depends_on_interrupt,
    depends_on_await_for,
    depends_on_reevaluate,

    # Configuration
    ConfigurationBuilder,
    MaivnConfiguration,
    get_configuration,
    MemoryAssetsConfig,
    MemoryConfig,
    MemoryInsightExtractionConfig,
    MemoryLevel,
    MemoryPersistenceMode,
    MemoryResourceConfig,
    MemoryRetrievalConfig,
    MemorySharingScope,
    MemorySkillConfig,
    MemorySkillExtractionConfig,
    SessionExecutionConfig,
    FinalOutputMode,
    OrchestrationMode,
    SessionOrchestrationConfig,
    StopStrategy,
    StructuredOutputConfig,
    SwarmAgentConfig,
    SwarmConfig,
    SystemToolsConfig,

    # Memory Resources
    MemoryInsight,
    MemoryInsightOrigin,
    MemoryInsightType,
    MemoryPersistenceCeiling,
    MemoryResource,
    MemoryResourceBindingType,
    MemoryResourceDetail,
    MemoryResourceStatus,
    MemorySkill,
    MemorySkillOrigin,
    MemorySkillStatus,
    MemoryUnboundResourceCandidate,
    OrganizationMemoryPolicy,
    OrganizationMemoryPurgeResult,
    ProjectMemoryResources,

    # PII / Privacy
    HIPAA_SAFE_HARBOR_CATEGORIES,
    PIIWhitelist,
    PIIWhitelistEntry,
    PrivateData,
    RedactedMessage,
    RedactionPreviewRequest,
    RedactionPreviewResponse,

    # Billing / Usage
    BillingUsage,
    BillingPlan,
    BillingCurrentUsage,
    BillingUsageBreakdown,
    BillingUsageProject,
    BillingUsageApiKey,
    BillingUsageTotals,

    # Permissions
    PERMISSION_FLAG_NAMES,
    PermissionFlag,
    PermissionSet,
    require_permissions,

    # Provider Metadata
    AuthMode,
    ProviderCapability,
    ProviderMetadata,

    # Logging
    configure_logging,
    get_logger,

    # Scheduling
    AtSchedule,
    CronInvocationBuilder,
    CronSchedule,
    IntervalSchedule,
    JitterDistribution,
    JitterSpec,
    MisfirePolicy,
    OverlapPolicy,
    Retry,
    RetryBackoff,
    RunRecord,
    RunStatus,
    Schedule,
    ScheduledJob,
    list_jobs,
    stop_all_jobs,

    # Terminal reporting and bridge policy
    BackpressurePolicy,

    # Interrupts
    AgentGenerated,
    FollowupOption,
    FollowupQuestion,
    FollowupQuestionsConfig,
    default_terminal_followup,
    default_terminal_interrupt,
)

Event and message APIs live in dedicated public submodules:

from maivn.events import AppEvent, EventBridge, RawSSEEvent, normalize_stream

from maivn.messages import HumanMessage, AIMessage, SystemMessage, RedactedMessage

Metadata-only run telemetry lives in its own versioned submodule:

from maivn.telemetry import RunTelemetryEvent, register_listener
from maivn.telemetry.opentelemetry import OpenTelemetryAdapter

Tip You rarely import all of this at once. Most applications need only Agent (or Swarm), one or two decorators, and the message types. Everything else is opt-in.

#Core classes

The objects you instantiate and call. Agent and Swarm are the two entry points. Both inherit a large shared surface from BaseScope (tool registration, events, batching, scheduling, and MCP). The .structured_output(Model) builder is Agent-only; Swarms use final tools for typed output.

#How an agent runs

When you call invoke() or stream(), the SDK compiles your tools, dependencies, and config into a request and hands it to the orchestrator. The orchestrator plans which tools to call (planning sees only the tool schemas, never your code), executes them locally in your process, and synthesizes a response. You read the result from InvokeResponse, or consume incremental StreamEvent values.

The async methods (ainvoke / astream) mirror the synchronous ones for native asyncio code, and batch / abatch run independent requests concurrently while preserving input order.

#Decorators

Decorators define tools and declare how a tool relates to other tools, agents, secret data, and the user. @toolify turns a function or Pydantic model into a tool; @toolset marks a class whose methods become tools. Dependency decorators are applied beneath @agent.toolify(...) (or beneath @swarm.member), or chained off the builder returned by toolify(...). See the Dependencies guide for the full data-flow model.

Artifact production uses generator toolsets from maivn-tools. These tools run in the user's tool environment and return GeneratedFile values through the normal artifact intake. Stored DOCX, XLSX, and PPTX files are downloadable but do not have an inline preview; PDF, PNG, and JPEG do.

from maivn import depends_on_tool

@agent.toolify(description='Fetch raw sensor data')
def fetch_sensor_data(sensor_id: str) -> dict:
    return {'sensor_id': sensor_id, 'readings': [72, 73, 71]}

@agent.toolify(description='Analyze sensor readings')
@depends_on_tool(fetch_sensor_data, arg_name='sensor_data')
def analyze_readings(sensor_data: dict) -> dict:
    readings = sensor_data['readings']
    return {'average': sum(readings) / len(readings)}

#Configuration

Two kinds of configuration exist. SDK configuration describes the environment (credentials, timeouts, defaults) and is usually built once from the environment. Session config models are typed objects that carry per-scope or per-call runtime controls; pass them to Agent(...) / Swarm(...) as defaults, or to invoke() / stream() as overrides.

#SDK configuration

#Session config models

Memory has a dedicated family of resource and policy models (MemoryInsight, MemoryResource, MemorySkill, OrganizationMemoryPolicy, and related enums). See the Memory and Recall guide for how they fit together.

#Privacy and private data

These models declare and govern sensitive values so the SDK can keep them out of model-visible context. The model plans against a schema of key names and types; real values are injected at tool-execution time, and tool results are scanned and redacted before returning to the model. See the Private Data guide.

These are technical controls, not certifications or guarantees. mAIvn holds no SOC 2, HIPAA, ISO 27001, or FedRAMP certification, cannot provide a BAA, and does not make a deployment compliant. Evaluate the controls at your own risk under the mAIvn Platform Disclaimer.

#Messages

Import message types from maivn.messages. These are the inputs you pass to invoke() / stream() and the assistant turns the SDK returns.

#Logging

#Events

The events surface lets you stream execution state (tool calls, phase indicators, the final response) into your own backend and frontend. The canonical normalize_stream() helper converts a raw stream into a stable, versioned AppEvent contract, payload builders construct individual event payloads, and EventBridge mounts an SSE endpoint. See the Events reference and the Frontend Events guide for the browser client example.

Note Enrichment events are fixed-label phase indicators (for example, "Evaluating request", "Planning actions", "Synthesizing response") streamed between tool calls so consumers can show what the system is doing. Status messages are a separate event family that may appear on the same stream.

#Decisions

The prepared maivn.decisions feature set provides categorical requests, locally authorized platform calls, fallback diagnostics, native batching, before/after invocation plans, typed arguments, function/local-tool dependencies and optional matching. Use the ordinary mAIvn key and platform address; no provider credential or model selector is exposed. See the Decisions API, guide and examples.

#Run telemetry

maivn.telemetry publishes the customer-visible run lifecycle as a closed, versioned metadata schema. The optional maivn[otel] adapter maps runs to traces and tool calls to spans without exporting messages, prompts, arguments, results, or resolved private values. See Run Telemetry.

#Scheduling

Any Agent or Swarm can run on a schedule. cron(...), interval(...), and at(...) return a chainable builder. A remote terminal call returns a durable Trigger. An explicit mode="local" call returns a process-owned ScheduledJob. See the Scheduling reference and the Scheduled Invocation guide.

#Token usage and billing

Responses expose runtime-reported token usage as an extensible dictionary. The public billing models validate aggregated plan and quota payloads, but the current public Client does not fetch those payloads. See the Billing reference and the Billing and Usage guide.

#Quick navigation by goal

• Build your first agent — Agent + Getting Started guide
• Define and wire tools — Decorators + Tools guide + Dependencies guide
• Request typed output — structured_output() on Agent + Structured Output guide
• Coordinate multiple agents — Swarm + Multi-Agent guide
• Connect external tools — MCP
• Stream events to a frontend — Frontend Events guide (one-line FastAPI mount + a browser client example); Events for the API reference and trust-boundary controls
• Export runs to an observability stack — Run Telemetry for metadata hooks and OpenTelemetry spans
• Run agents on a schedule — Scheduling + Scheduled Invocation guide
• Make categorical decisions — Decisions API + guide
• Handle secrets and PII — Private Data guide
• Tune memory and recall — Session Config Models + Memory and Recall guide
• Configure the SDK environment — Configuration
• Track tokens and usage — Usage and Cost + Billing + Billing and Usage guide
• Debug — Logging + Troubleshooting

#Next steps

• Getting Started — your first agent, end to end
• Agent reference — the full Agent and BaseScope surface
• Shared Data Models — the typed shapes you read off responses and pass in
• Examples — a runnable tour organized by what you want to build
• Best Practices — production patterns

#Version

from maivn import __version__
print(__version__)