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 validates the marketplace release manifest and creates a DRAFT only.

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.