Platform capabilities
Explore what mAIvn does, from the first Python function to a run you can inspect. Open the developer details when you want the API behind a feature.
Watch the approval workflow Build
Your team builds agents with the code they already write, so there is nothing new to learn before the first one runs. Ordinary functions become tools an agent can use, with no diagram to draw and no wiring to fill in by hand.
Add one line above a normal Python function, or above a typed Python model, and an agent can use it. Everything the agent needs to know about it comes from the type hints you already wrote.
@agent.toolify() on a function or a typed model. The schema comes from your type hints
Only a tool's name, its description and the kinds of values it takes ever leave your systems. The code itself runs where you run it.
Only compiled tool metadata is sent. maivn serve runs the body in your own process
Put several specialists together into one team you call exactly like a single agent, and say plainly who hands work to whom.
Swarm with swarm.member(...). SwarmConfig and SwarmAgentConfig declare the roster
Tell the platform which tool feeds which. Work that can happen at the same time does, work that has to wait waits, and you write none of that scheduling yourself.
@depends_on_tool, @depends_on_agent and @depends_on_await_for on the consumer
Get data back in the shape you defined, already checked, or a clear explanation of why it could not be produced. You never have to repair a half-formed answer by hand.
agent.structured_output(Model) or invoke(structured_output=Model), with typed failures
Deeply nested results come back complete on every model we support.
Large nested structured_output= models are supported. Failure raises MaivnSDKError
Save reusable instructions as plain Markdown files and group them into sets. Attach a set to an agent, or let the right set be chosen for each run.
Skill and SkillSet via parse_skill_markdown. Attach per agent or select per run
Each tool carries a written list of what it is allowed to touch, and a flag when it can destroy something. What an agent can reach is declared, not assumed.
@toolify(permissions=..., destructive=True), with PermissionFlag and PermissionSet
Slip your own code in immediately before and after any tool runs, for logging, policy checks, or anything else you need in the path.
before_execute and after_execute on @toolify, with hook_execution_mode tool or scope
Every way of calling an agent comes in two forms, one that waits for the answer and one that gets on with other work, so the same code suits a small script and a busy web service.
Every call has an async twin: invoke/ainvoke, stream/astream, send/asend
Push a whole list of inputs through one agent and compare the results side by side, from your own code or from Studio.
Batch from the SDK, or the Batch Matrix in Studio with per-variant comparison
Call your tools straight from your test suite and inspect exactly what an agent would be told about them, standing in for only the remote part. Tests stay fast and give the same answer every time.
agent.compile_tools(), agent.list_tools(), agent.validate_tool_configuration()
The toolkit you install, the SDK, needs Python 3.10 or newer. Everything you pass in and get back is typed, so your editor and your tests catch mistakes before a run does.
SDK floor is Python 3.10. Requests, responses and events are typed Python models
Choose
Nobody on your team has to keep up with every new AI model to get good answers at a sensible price. Ask for the outcome you want, and the platform picks a model to match, switches when one falters, and writes down what it chose.
Leave the model unset and each request goes to one that suits it. Routine work stops costing you top-of-the-range prices.
model='auto' is the default. Each request is matched without you naming a model
Choose fast, balanced, max, ultra or automatic instead of naming a particular model. When you need the identical model every single time, name one.
model='fast' | 'balanced' | 'max' | 'auto', or ModelChoice(model_id=...) to pin one
Use one model for the answer, another for thinking a problem through, and others again for planning, writing code or filling in a complicated tool call.
ModelConfig(response=..., thinking=..., repl=...), or ModelConfig.for_all(...)
Nudge the automatic choice in the direction you care about, without having to make the decision yourself.
A speed, cost or quality preference on the run. Unset parts of ModelConfig follow it
Set how much thinking a request gets, from barely any to a great deal. If a provider does not offer the depth you asked for, the nearest one it does offer is used instead of the call failing.
reasoning='minimal' | 'low' | 'medium' | 'high', mapped to the nearest a provider has
Anthropic, Google, OpenAI and more all work the same way in your code, with picture generation wherever a provider offers it. mAIvn keeps adding new models as they come online, with no change on your side.
Anthropic, Google, OpenAI and more behind one Agent surface. New models are added as released
Thinking settings, length limits, insisting on a particular tool and the shape of the result all behave the same on every model, even where the providers themselves disagree.
Reasoning, output caps, forced tool choice and schema rules behave the same on every provider
If a provider slows to a crawl or goes down, the work carries on with another one. You do not write the retry.
Failover to another provider happens inside the call. You write no retry loop
A provider that stops responding is spotted and swapped out, rather than left to keep your request hanging.
A provider that stops streaming is treated as failed and the call moves on. Nothing hangs
When a conversation keeps repeating the same background material, the provider is asked to reuse it. Long conversations cost less and start answering sooner.
Provider prompt caching, counted as cache_read_tokens and cache_creation_tokens
The list of models, what each one can do and what each one costs is versioned, so it cannot change quietly underneath you.
A versioned model list. What each model supports and costs is fixed for that version
When the platform chooses for you, the record of the run says which model served the request and what kind of work it was matched to.
The served model is on the trace and in response.provider_usage.by_model
Pictures, documents and video only go to models that can genuinely take them in. Nothing answers as though it had read a file it never saw.
Attachments go only to models with native support, or the call is refused outright
Agents always know today's date and the local time for the person they are working for.
client_timezone and auto_detect_timezone put the caller's local time in context
Run
This is the part most teams underestimate: deciding what runs when, catching work that has gone wrong, and staying inside a budget. It comes with the platform, so nobody on your side has to build it.
Work that does not depend on anything else runs at the same time, and work that does runs in order. You say what depends on what; the platform arranges the rest.
Independent tool calls are scheduled together. Declared dependencies run in order
Every step of a multi-step run keeps a stable identity, so a finished run can be stepped through afterwards, exactly as it happened.
Every step has a stable identity in the trace, so a finished run replays step by step
A smaller task inside a bigger one can be given its own tools, its own budget and its own view of the data, so one part of the work cannot reach into another.
A sub-job carries its own tools, model choice, data scope and spend ceiling
When several agents work together, their plan is checked before anything runs. A plan that does not hold up falls back to a safe one instead of failing the whole job.
A team's plan is validated before any member runs. An invalid plan falls back to every member
You can insist that a run finish by calling one particular tool, so the last thing an agent does is always the thing you asked for.
final_tool=True on the tool, with force_final_tool=True on the run
When something keeps failing, the work moves up to a stronger model one time and then finishes. A struggling run cannot quietly spend your whole budget.
Repeated failure escalates one step, then finalizes. It never loops your budget
Mark the places where an agent has to pause and think again, instead of letting it carry on with a plan that is already out of date.
@depends_on_reevaluate(...) marks the tool the agent must re-plan around, shown in the stream
Web search, a safe place to run Python, a focused deep-thinking pass and help filling in complicated tool inputs are all there from the start, with nothing to set up.
SystemToolsConfig(allowed_tools=...): web_search, repl, think, reevaluate
Accuracy holds up as the number of tools you have grows, and you can narrow the set yourself for any one run.
targeted_tools= on a run limits the agent to the tools you name
A budget is checked before a call goes out, rather than discovered on the bill afterwards.
Limits are checked before a call goes out. A refused call raises a typed error and bills nothing
Protect
If your work touches customer records, payment details or medical information, this is the section to read. Values you declare, and supported values the safety scanner detects, are replaced before configured model requests. Approved tools and final responses can receive restored values; tools, outputs, logs, customer storage and file custody need their own controls. On supported desktops, the SDK saves caller-declared values in an encrypted local vault when an OS credential store is available.
An agent works with the name and the kind of a sensitive value, a card number for instance, and never with the number itself.
PrivateData(value=, name=, pii_type=, label=). The model plans on the descriptor
A tool you configure can receive the true value at the moment it runs. Tool arguments, results and logs still need the access and retention rules you choose for that tool.
@depends_on_private_data(data_key=..., arg_name=...) injects at execution time
Authorized final responses can restore protected values before the person reading them receives the answer. Multi-turn work also needs thread custody for its placeholder map, so retention follows the configured store and lifecycle.
Restoration is scoped; thread custody supports multi-turn placeholder resolution
Sensitive details that turn up unannounced in a tool's result, such as card numbers, account numbers, bank details and people's names, are recognized and taken out before the model ever sees them.
Tool-result scanning on RedactedMessage flows. Allow-list via PIIWhitelist
A value that a tool splits up, reorders or writes out differently is still recognized, and still removed.
known_pii_values matching survives splitting, reordering and reformatting
List the things you are happy to pass along. A stricter setting refuses a list that would give away a sensitive category.
PIIWhitelistEntry(entity_type= | value= | pattern=, justification=), plus phi_mode
For any session, see every time a sensitive value was used and which step used it.
Every resolution of a private value is recorded per session, with the step that used it
Anything an agent learns and keeps is stored without sensitive values inside it, so remembering cannot leak what was removed.
Enrichment writes memory with private values stripped, so recall cannot leak them
A multi-turn run needs its placeholder map to continue. On supported desktops, the SDK saves caller-declared values in an encrypted local vault when an OS credential store is available. You can configure the store or disable persistence.
private_data_store=None opts out; forget_private_data(thread_id) deletes saved caller values
Check exactly what would be taken out before you send anything at all.
RedactionPreviewRequest and RedactionPreviewResponse, before anything is sent
Files are stripped of sensitive detail before any model sees them, and every time a real value is put back the record shows where it came from.
Attachments on a RedactedMessage are redacted first. Each restoration is stamped
Sensitive writing and faces are removed from images, not only from text. If the cleaning cannot be trusted, the file is held back rather than passed on.
Image redaction on the secure handling path. An uncertain result quarantines it
Run history keeps the conversation so you can replay it, with private values left out. The feed you send to your own monitoring is different: it holds labels and counts only, and there is nowhere in it to put a prompt or an answer.
maivn.telemetry events and OpenTelemetry spans carry no prompt, argument, result or payload
The local vault core encrypts value maps and documents on your machine. The SDK sets up storage for caller-declared placeholder values on supported desktops; private-file custody remains a separate API.
Automatic local placeholder storage; explicit path and secret settings for headless use
The local vault can purge its active ciphertext records. That does not prove deletion from backups or from every outside system that received a copy.
Local hard purge covers active vault records; external copies need separate deletion
Connect
An agent is only as useful as the systems it can reach, and reaching them should not become a project of its own. Adding one is an import in your code, not an integration effort.
One optional package brings 170+ ready-made connections. It covers AI services, search, databases, analytics, data pipelines, chat, email, documents, developer tools, infrastructure, sign-in, customer records, commerce, finance, staffing, service desks, social tools, and automation hubs.
One optional package: 170+ connectors registered as toolsets via @toolset(prefix=...)
Point at a web address, at a published description of a service, or at a single operation, and you get tools you can call. The usual kinds of web interface are covered, with no generated code to keep in step.
REST, OpenAPI and GraphQL surfaces become typed tools with no generated code
Attach any server that speaks the Model Context Protocol, an open standard for connecting tools to AI, over a local link or the web. Its tools then behave like your own, errors and run records included, and anything that looks like a password stays hidden from the model.
MCPServer(transport='http' | 'stdio'), or MCPAutoSetup(package=...) by name
Keys, tokens, usernames and the common sign-in handshakes are all taken care of. When a connection needs signing in again you get a clear signal, so your own screens can ask at the right moment.
AuthMode and ProviderCapability on ProviderMetadata, with typed re-authorize errors
Backing off politely when a service is busy, staying under its limits, and walking through long lists of results are built into every connection, rather than rewritten for each one.
Retry with backoff, rate limiting, and cursor, offset, page-token and delta paging
See what a write would do before it does it, so anything destructive gets reviewed rather than discovered.
A write can be previewed before it runs. destructive=True marks the ones that bite
Link a project to chat, code hosting, email, databases, incoming events, forms, or local files once. Do it in the Portal or from the command line.
maivn connections create --kind ...: saved per project, reused by every agent
Automate
Most of the value arrives when nobody has to press anything: work begins on its own and the answer turns up where your team already works. It also cannot run away with itself, fire twice, or flood you.
Work can begin on a timetable, at the press of a button, or when an email arrives for an agent. It can also start from a signed message, another run finishing, an event in a connected service, something being saved or remembered, a reply in a thread, or an agent deciding to start one itself.
agent.on_webhook, on_email, on_record_change, on_form, on_file_change, more
Results go to your chat, a comment on your code, an email reply, a record in your database, a web address of yours that we call, a file, or the app itself. Delivered once.
.to_connection('conn_...') or .display_in_app() on the trigger builder
Runs that repeat are staggered so they do not all fire at once, and after an outage they pick up cleanly instead of replaying everything they missed.
JitterSpec(min=, max=, distribution=) plus misfire catch-up after downtime
Incoming events are accepted the moment they arrive and stored safely. A restart does not lose them.
Signed events are acknowledged on arrival and durably queued before a run starts
The same event arriving twice never does the work twice, and a tampered-with copy is refused outright.
The same signed delivery id and body acknowledges as duplicate. A changed body is refused
An automation cannot set itself off in a loop, one event cannot snowball into a flood, and a failing connection is cut off before the trouble spreads.
Loop, depth and fan-out limits per trigger. A repeatedly failing connection is paused
An event that does not lead to a run says exactly why, by name, instead of quietly disappearing.
Every event that does not run gets a named reason on its receipt
Automated work in the background cannot crowd out someone waiting on an answer right now.
Interactive calls take priority over automated runs
Decide for each automation how often to retry and how long to wait between attempts. Work that runs out of attempts lands somewhere you can look at it and send it through again.
Retry(max_attempts=, backoff='constant' | 'linear' | 'exponential', max_delay=)
Work that is tried again uses the version of the agent that first received the event, so a release in the meantime cannot change the answer.
.target(agent_id, version=...) pins the version that first received the event
Every message we post to a web address of yours is signed and stamped with the time, so your systems can check that it really came from us.
Outbound deliveries carry a signature and a timestamp your endpoint can verify
Outgoing deliveries are blocked from reaching addresses inside a private network.
Outbound delivery refuses private network addresses
Serve agents from your own machines without opening a single incoming port. Work is picked up rather than pushed in, so the same job cannot run twice.
maivn serve module:attr on the default worker transport: pull-based, no inbound ports
Point a real outside service at code running on your own machine, through a temporary secure link.
maivn dev-tunnel --connection-id ... gives a temporary HTTPS callback URL
Send signed notices when files change on a computer you control, without putting that computer on the internet.
maivn watch-files <path> --watch-id --connection-id --glob, sending signed change events
Produce
The work you care about usually lives in documents, spreadsheets and scans rather than in tidy text. Agents can read those files honestly and hand back finished ones.
Attach text, pictures, documents, or video to any message. The agent works from what is genuinely in the file.
Text, image, document and video blocks on any Message, one Attachment per file
Pick speed, or a tidied-up version you can navigate, or the careful setting, which strips sensitive detail out of both the words and the pictures before any outside model sees the file.
Direct for speed, indexed for clean text and navigation, or secure for redaction
Documents, spreadsheets, exported data, web pages and plain text all come out as consistent, readable text, and spreadsheets keep their rows and columns.
Documents, spreadsheets, delimited data and web pages convert to plain Markdown
Text is read out of scanned pages and photographs, and audio and video are written out as text. A page that cannot be read is reported as unreadable, never invented.
Scans and photos are read. Audio and video are transcribed. Unreadable is reported
A partly corrupted document still comes through readable instead of ruining the whole run.
Partly corrupt documents are recovered rather than failing the whole run
Rather than cramming a whole document in at once, agents move through it section by section, and every answer points at the part it came from.
Agents move through a document by section. Every answer cites the section it came from
Agents produce word-processor files, PDFs, slide decks, spreadsheets and pictures. They are built the same way every time, and you can look at them in Studio before they go anywhere.
DOCUMENTS_compose_artifact and kin. PDF, PNG and JPEG preview inline in Studio
Create and edit images without tying yourself to one provider, with a safety setting you choose rather than inherit.
Provider-neutral image generation and editing, with a safety level you set
Every file an agent makes is traceable to the step that made it, and is handed over only once it is complete.
response.artifact_refs carries mime_type, custody and logical_output_id
A tool you wrote can hand a file straight back. There is nothing extra to build on our side of the line.
maivn.files.generated_file(path) with a GeneratedFile return annotation
Upload the documents your agents refer to, swap them, restore them, clean them again, and reuse them across runs.
create_memory_resource, bind_memory_resource, replace_memory_resource, restore
Remember
Some work spans days and several people, and some of it should not happen until somebody signs off. Agents carry what they have learned, ask a question when they need one answered, and wait.
One conversation keeps its context from one turn to the next, with plain controls if you would rather manage that yourself.
client.thread(thread_id) returns a BoundThread with send, stream and state
Choose anything from remembering nothing at all to full recall, and decide whether that memory belongs to one agent, a team, a project, or the whole organization.
MemoryConfig(level='none' | 'glimpse' | 'focus' | 'clarity', sharing_scope=...)
Agents pull reusable lessons and know-how out of their runs, and you decide what is worth keeping, in the Portal or from your own code.
MemorySkillExtractionConfig and MemoryInsightExtractionConfig. Curate in the Portal
The work of learning happens after the answer has already gone out, and it still shows up properly in your usage.
Enrichment runs after delivery, with client.memory.enrichments.list(session_id) receipts
A remembered fact carries its origin, so you can see which run taught it.
Recalled facts carry provenance: skill_hits, insight_hits, resource_hits
Set a memory policy for the whole organization and how long things are kept, and clear memory with a record of exactly what went.
update_organization_memory_policy(...) sets the persistence ceiling and retention
Stop a run for someone to decide before a tool does anything, then carry on from exactly where it stopped.
submit_approval(...) with ApprovalDecision(approved=, decided_by=)
Agents can ask a proper question, from yes or no to pick one, pick several, write something, or fill in a short form, and then pick up precisely where they paused.
agent.allow_followup_questions(...), asking a FollowupQuestion with FollowupOption choices
Rewind a conversation to an earlier turn and take it in a different direction, without losing the original.
time_travel_thread(...) branches from an earlier position, original left intact
Stop a run while it is still going, rather than waiting for work you no longer want.
client.cancel(session_id) stops a run that is still executing
Observe
When an agent gets something wrong, the question is always the same: what did it actually do? Every run is watchable while it happens and inspectable afterwards, in our apps or in yours.
Text, tool calls and progress markers appear as they happen. Lose your connection part way through and you pick up again with nothing missed and nothing repeated.
stream/astream yield StreamEvent(position=...). Resume via resume_from_position
A searchable tree of every model call, every tool call, every switch to another provider and every helper agent, with how long each one took and how much it used.
A searchable tree of model calls, tool calls, provider hops and sub-agents, timed
See the cost of each step of a run, charged against the model that really served it rather than the one you asked for.
response.provider_usage broken down by_model, against the model that served it
Feed run records into the monitoring you already use, through OpenTelemetry, the open standard for tracing. Sensitive values are left out by the shape of the record itself.
maivn.telemetry.opentelemetry (optional [otel] extra), with metadata-only spans
Let your users watch an agent work inside your product. It is one line in FastAPI, with ready-made bridges for Flask, ASGI, aiohttp and Django, and building blocks for whatever your front end is written in.
mount_events(app) from maivn.events.fastapi, or EventBridge.generate_sse elsewhere
Scan a project, run any agent, read the record, answer its questions, run batches and compare them, schedule work, browse the files it produced, and replay or branch through history. The first sample run needs no network at all.
maivn studio: Scan Repo, Batch Matrix, and the Inspect / Recall / Config / Schedule tabs
Runs and conversations with their records, spend by model, agent, project and key, your most expensive runs, invoices, teams, keys, connections, delivery history, memory curation, and documentation with an assistant built in.
Runs and threads, usage by key and project, API Keys, Webhooks, Memory Resources
The reference for our interface is generated from the running service, so it cannot drift out of date.
The API reference is generated from the service itself, never maintained by hand
When the platform cannot tell whether something finished, it records that it does not know rather than guessing, and never charges you twice to settle the question.
An unresolved outcome is recorded as unknown rather than guessed, and never rebilled
Operate
Set access for each project and see where usage comes from. Choose how additional capacity is purchased when a project reaches its limits.
Use owner, admin, member, or viewer roles. Invite people by email and set membership for each project.
Organization roles owner, admin, member and viewer, with membership set per project
A key is shown once, listed afterwards with most of it hidden, stamped with when it was last used, and switched off everywhere within seconds.
Portal API Keys, per project: shown once, listed masked, revoked everywhere in seconds
You are warned as you approach a limit and stopped when you reach it. Buy extra capacity or opt into automatic reloads, available at general availability. If a limit is missing, work is refused.
Warned before a limit, stopped at it. Reloads priced per million standard tokens, auto-reload opt-in
Break down usage by project and API key, then export the figures as a spreadsheet through the API.
BillingUsage with breakdown by project and API key, plus spreadsheet export by API
Start
You can try this in an afternoon, from wherever you already work. There is nothing to deploy and nothing to buy before the first run.
Install the package, mark one function, and call your first agent. There is nothing to deploy before the first run.
pip install maivn, decorate a function, call agent.invoke(...). Nothing to deploy
Serve agents, open a temporary link for testing, watch local files, manage connections and launch Studio, all from one command.
maivn serve, dev-tunnel, watch-files, connections and studio, from one command
Studio runs, records and replays your agents on your own computer, and its first sample run works with no network at all.
maivn studio with --host, --port and --no-browser. First sample run needs no network
Sign in to the Portal to run agents, read the records, connect systems, invite your team and handle billing.
Sign in to the Portal for runs, traces, connections, team management and billing
Written guides, a complete reference and runnable examples you can paste straight into your own project.
Guides, a full API reference and runnable examples in the public documentation
Guided demos show tools, private data, teams of agents, approvals, structured answers and work running in parallel, all together in one place.
Worked demos covering tools, private data, swarms, interrupts and structured output
Private-data controls need deliberate configuration. They do not replace your compliance responsibilities.
Privacy control, not certification: mAIvn holds no SOC 2, HIPAA, ISO 27001, or FedRAMP certification. Use it at your own risk under the Platform Disclaimer.
Automatic detection of sensitive data is a safety net, not a guarantee of complete coverage. Declare the values that matter to you rather than relying on detection alone.
The SDK supports automatic encrypted local placeholder storage on desktops with an available OS credential store. Headless use needs an explicit secret or configured credential backend. Hosted managed vault custody is not available.
Eligible organizations can enable automatic reload when billing is enabled and a payment method is saved. Confirm availability and limits in your Portal. Storage and concurrent-job limits shown in plan details are not yet enforced.
Start with one task. Follow the setup guide, then use the API reference as you build.