vintraa-agent

vintraa-agent is the Python SDK for native Vintraa agent integrations, with a framework-neutral core and an optional FastAPI adapter.

This package is an alpha release. Its API may change before 1.0.0.

python -m pip install vintraa-agent
# FastAPI and Redis adapters:
python -m pip install 'vintraa-agent[fastapi,redis]'

See the Vintraa developer guide and public API reference. Using the SDK is optional and does not itself certify an agent.

from vintraa_agent import (
    AsyncInMemoryIdempotencyStore,
    HostedPublicKeyProvider,
    InvocationExecutor,
    SuccessResult,
)
from vintraa_agent.fastapi import create_fastapi_router


async def generate_roster(invocation):
    return SuccessResult(
        output={
            "workspaceId": invocation.envelope.context.workspace.id,
        }
    )


async def authorize(invocation):
    return "ROSTER_MANAGER" in invocation.envelope.context.user.roles


executor = InvocationExecutor(
    public_keys=HostedPublicKeyProvider(),
    idempotency=AsyncInMemoryIdempotencyStore(),  # use Redis in production
    handlers={"roster.generate": generate_roster},
    authorize=authorize,
)

app.include_router(create_fastapi_router(executor))

The FastAPI adapter streams and bounds the untouched request body before verification; tune max_body_bytes only when the signed protocol limit changes. Use AsyncRedisIdempotencyStore with redis.asyncio in multi-process production; the in-memory store is development-only. PublisherClient.register_draft remains a compatibility alias. PublisherClient is an equivalent async client for canonical contract 2026-09-05.11: device identity, scoped credentials, ownership verification, publishers, applications, releases, conformance, private test creation, publisher-safe review responses, certification reads, controlled activation/deprecation/withdrawal, deployment upgrade/rollback, principal-owned import/conformance jobs, governed assets and asset sets, conformance history, signed publisher webhook lifecycle/history, ETags, cursors, and Operations. Publisher analytics add the closed event dictionary, privacy-gated summary and timeseries reads, plus idempotent aggregate-only exports with a dedicated typed operation poll. Suppressed values remain None, unknown optional SDK coverage remains UNKNOWN, and truncation is explicit. Successful analytics responses are hard-bounded to 1,000 cells or rows and use a dedicated bounded decoder so the contract maximum remains consumable. It validates manifest v2 before mutations; review and certification remain server-authoritative. See the raw HTTP operation guide.

Publisher webhook verification requires the untouched request bytes:

from vintraa_agent import verify_publisher_webhook

verified = verify_publisher_webhook(
    raw_body,
    request_headers,
    {current_secret_prefix: current_secret},
)

Persist verified.event_id in a durable inbox before side effects. HMAC and freshness verification do not themselves deduplicate retries or order events.

Anonymous discovery uses MarketplaceClient, which deliberately sends no bearer credentials:

from vintraa_agent import MarketplaceClient

marketplace = MarketplaceClient()
page = await marketplace.search_applications(category="productivity", limit=25)
passport = await marketplace.get_application(page["items"][0]["appId"])

Authenticated install and reputation mutations remain on PublisherClient; workspace role, acknowledgement, eligibility, and moderation stay server-authoritative.

Hosted signing-key discovery uses a bounded negative cache, a refresh cooldown, a rolling fetch-rate cap, and one in-flight refresh so attacker-controlled key identifiers cannot amplify registry traffic.

For a developer-hosted customer UI, use create_external_experience_exchange_proof on the server that receives Vintraa's top-level launch POST. Keep both the private key and exchanged access token out of browser JavaScript and browser storage.