vanty-ai 0.3.3

Vanty App: pydantic-ai agent runtime, capabilities, threads, usage metering, tool approvals.

vanty-ai

vanty-ai packages reusable Pydantic AI capabilities and runtime helpers for Vanty apps.

Included

• Tortoise models for agent threads, persisted messages, approval requests, and usage events.
• A thread lifecycle capability that keeps thread state and message history in sync with agent runs.
• A tool approval capability that marks selected tools as requiring approval, persists approval requests, and emits generic notifications.
• A usage metering capability that captures token and cost snapshots from ModelResponse objects.
• A logging capability for run- and tool-level observability.
• A thin AIApp compatibility helper for ORM setup and assembling a default capability bundle.

Public API

The package root intentionally exports only the main consumer-facing surface:

from vanty_ai import (
    AIApp,
    AISettings,
    AgentRuntimeDeps,
    LoggingCapability,
    ThreadCapability,
    ToolApprovalCapability,
    UsageMeteringCapability,
    apply_approval_decision,
    approval_requests_to_deferred_results,
    build_default_capabilities,
)

Lower-level persistence models, services, and integration helpers are available from their explicit modules instead of being re-exported from vanty_ai.

Quick start

from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
from pydantic_ai.tools import DeferredToolRequests

from vanty_ai import AIApp, AISettings, AgentRuntimeDeps, build_default_capabilities

kit = AIApp(AISettings(database_url="sqlite://./vanty-ai.db"))
await kit.init_orm(generate_schemas=True)

agent = Agent(
    model=TestModel(custom_output_text="done"),
    output_type=[str, DeferredToolRequests],
    capabilities=build_default_capabilities(),
)

deps = AgentRuntimeDeps(
    organization_id="4d65fcb6-6d1d-4701-8b1c-b95ee7e2476d",
    actor_user_id="6e8372a2-6e84-4c74-b28f-4ec8e52cf7af",
    thread_title="Support chat",
    channel="web",
)

result = await agent.run("Hello", deps=deps)
print(result.output)
print(deps.thread_id)

Model configuration

AgentService works offline by default with Pydantic AI's TestModel. In production, set AI_MODEL to any Pydantic AI model string, or provide one of the supported provider keys:

# Preferred explicit configuration
AI_MODEL=anthropic:claude-3-5-haiku-latest
ANTHROPIC_API_KEY=...

# Or OpenRouter
AI_MODEL=openrouter:z-ai/glm-5.1
OPENROUTER_API_KEY=...

If AI_MODEL is not set, ANTHROPIC_API_KEY selects anthropic:claude-3-5-haiku-latest, OPENROUTER_API_KEY selects openrouter:z-ai/glm-5.1, and OPENAI_API_KEY selects openai:gpt-4o-mini.

Embedded support chat

The bundled FastAPI router exposes /ai/embed/* for customer-facing support widgets:

• POST /ai/embed/sessions creates a browser session and returns a signed token.
• GET /ai/embed/sessions/me restores the session for the current browser.
• GET/POST /ai/embed/threads lists and creates session-scoped conversations.
• GET/POST /ai/embed/threads/{thread_id}/messages restores history and runs the agent.
• POST /ai/embed/files registers browser file references for attachment-aware agents.

Embedded tokens are separate from internal user auth. Configure AI_EMBEDDED_TOKEN_SECRET and AI_EMBEDDED_TOKEN_TTL_SECONDS for deployments, and create EmbeddedAgentConfig rows from the host application's admin surface to control origins, branding, and capabilities.

Thread history

Thread/message persistence is routed through service and persistence modules. To resume a run with previous model history, import the history helper from its explicit service module:

from vanty_ai.services.history import load_thread_history

Approval flows

Use ToolApprovalCapability to convert matching tools into Pydantic AI unapproved tools. When the model requests one, the capability persists approval request rows and publishes a notification event through a pluggable sink.

To resume a run, turn approved or denied requests into DeferredToolResults:

from vanty_ai import approval_requests_to_deferred_results, apply_approval_decision

Operational approval models and status enums live under vanty_ai.persistence.models.

Usage and payments integration

UsageMeteringCapability persists local usage rows by default. If you want real billing meter events, compose the default local recorder with the optional payments recorder:

from vanty_ai.integrations.payments import PaymentsMeterRecorder
from vanty_ai.services.usage import CompositeUsageRecorder, TortoiseUsageRecorder

usage_recorder = CompositeUsageRecorder(
    [
        TortoiseUsageRecorder(),
        PaymentsMeterRecorder(
            billing_service=billing_service,
            account_resolver=resolve_account_from_usage_context,
        ),
    ]
)

Payments integration receives explicit usage context on every record call; it does not require mutable bind(ctx) state.