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-06.1: device identity, scoped credentials, ownership verification, publishers, applications, releases, conformance, private test creation/run/reset, 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.

The high-level helper runs the same server-authoritative review workflow without persisting a token. Its default selector uses manifest-declared synthetic input; inject select_test only when the manifest offers more than one intentional test.

from vintraa_agent import PublisherClient, publish_release_for_review

client = PublisherClient(token_provider=short_lived_token)
result = await publish_release_for_review(
    client,
    release_id,
    manifest,
    confirm=confirm_human_review_submission,
    attempt_id=persisted_attempt_id,
)

The sequence first binds Vintraa's assigned appId when the authoring manifest legitimately omits it, then verifies that the server draft digest exactly matches that expected manifest. Legacy v1 reconciliation also permits only trailing CR/LF removal from customerExperience.clientAuthentication.publicKey and materializing omitted test-step bindings as []; evidence uses the authoritative server form. No other server/local drift is accepted. It then validates, waits, creates a digest-bound private installation, runs one synthetic action, runs conformance, waits, confirms, and submits. A stale manifest, failed evidence, or declined confirmation stops before submission. It never approves, certifies, or activates. Private-test inputs and responses become test evidence: never use customer records, credentials, or secrets. Omit attempt_id to derive a stable default from the release and exact manifest digest. Repeating the same workflow after an ambiguous process crash then reuses the same backend intent. After observing a definitive terminal failure, pass a new safe attempt ID so the repaired deployment is actually retested.

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.