#SDK Reference

The complete public surface you import from maivn — every class, decorator, config model, and helper, grouped by area with links to the detailed per-class 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 — SessionResponse, TokenUsage, 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 Agentfrom 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 SessionResponse. Tool code runs locally in your environment — the SDK sends only tool schemas (names, descriptions, parameters) for planning.

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

#The public import surface

Everything below is exported from the top-level maivn package. The spine reads top-down: the core classes you instantiate, the decorators that wire tools together, the configuration that shapes behavior, then events, scheduling, and 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,    compose_artifact_policy,     # 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,     # Events    APP_EVENT_CONTRACT_VERSION,    AppEvent,    BackpressurePolicy,    BridgeAudience,    BridgeRegistry,    EventBridge,    EventBridgeSecurityPolicy,    NormalizedEventForwardingState,    NormalizedStreamState,    RawSSEEvent,    UIEvent,    build_agent_assignment_payload,    build_assistant_chunk_payload,    build_enrichment_payload,    build_error_payload,    build_final_payload,    build_interrupt_required_payload,    build_session_start_payload,    build_status_message_payload,    build_system_tool_chunk_payload,    build_system_tool_complete_payload,    build_system_tool_start_payload,    build_tool_event_payload,    forward_normalized_event,    forward_normalized_stream,    normalize_stream,    normalize_stream_event,     # Interrupts    default_terminal_interrupt,    get_interrupt_service,    set_interrupt_service,)

Message types live in a dedicated submodule:

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

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, structured output, events, batching, scheduling, MCP).

#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 off the returned SessionResponse, or consume incremental SSEEvents from the streaming variants.

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. The depends_on_* and compose_artifact_policy 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.

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 they never reach the model in cleartext. The model plans against a schema of key names and types; real values are injected only at tool-execution time, and tool results are scanned and redacted before returning to the model. See the Private Data guide.

#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 client examples across many languages.

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, opt-in channel enabled with stream(status_messages=True).

#Scheduling

Any Agent or Swarm can run on a schedule. cron(...), every(...), and at(...) return a chainable builder; calling a terminal method (invoke / stream / batch and async variants) schedules the job and returns a ScheduledJob handle. See the Scheduling reference and the Scheduled Invocation guide.

#Token usage and billing

Token usage is captured per LLM call, normalized across providers, and aggregated for the session, so responses surface input/output/total token counts (including cache reads and reasoning tokens) alongside the model and provider. For account-level reporting, the public billing/usage models — BillingUsage, BillingPlan, BillingCurrentUsage, and the BillingUsageBreakdown / BillingUsageProject / BillingUsageApiKey / BillingUsageTotals family — expose aggregated usage and plan/quota information via Client.get_usage(). 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
• Get guaranteed 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 + client examples in many languages); Events for the API reference and trust-boundary controls
• Run agents on a schedule — Scheduling + Scheduled Invocation 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 — 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__)