ViksaAIDocs
Start now

Python SDK

Package viksa-ai on PyPI — the agent runtime, API client, and dev tooling. Preinstalled on platform workers.

Install

Terminalsh
pip install viksa-ai

# optional: validation CLI + pytest helpers
pip install "viksa-ai[dev]"

Source and changelog: github.com/viksa-ai/viksa-sdk. Monorepo copy: viksa-ai-workspace/viksa-sdk.

Agent runtime (viksa_ai.runtime)

The same import works everywhere — the dashboard editor, local development, and CI. The SDK is preinstalled on platform workers; never vendor a ViksaAI.py file.

main.pypy
from typing import Any, Dict

from viksa_ai.runtime import mcp_endpoint, ViksaAuth, ViksaAuthError

@mcp_endpoint(description="Look up a record by id")
async def get_record(payload: Dict[str, Any]) -> Dict[str, Any]:
    record_id = payload.get("record_id")
    try:
        token = ViksaAuth.require_param("api_bearer", "token")
    except ViksaAuthError as exc:
        return {"ok": False, "error": str(exc)}
    # use token in httpx/aiohttp — never log secrets
    return {"ok": True, "id": record_id}
Runtime importpy
# One import everywhere — platform editor and local dev:
from viksa_ai.runtime import mcp_endpoint, ViksaAuth, ViksaAuthError

# The viksa-ai SDK is preinstalled on platform workers.
# For local development: pip install viksa-ai
# (Nothing is injected anymore — never vendor a ViksaAI.py in your repo.)
  • @mcp_endpoint — marks an async tool; description is shown to planners and validators.
  • ViksaAuth — reads vault-backed secrets as method_id.param_name env vars. See Auth & credentials.
  • ViksaAuthError — raised when a required auth method or param is missing; return structured errors from endpoints instead of bare tracebacks when possible.
  • context() — read A2A correlation metadata on agent-to-agent calls (optional).

Step-by-step agent authoring: Creating agents, Endpoints.

Development tooling (viksa_ai.devtools)

Run the same manifest checks the platform uses before build/deploy: required main.py, endpoint names, @mcp_endpoint on each declared function, async + single payload argument, and input/output references.

Validate before pushsh
# Validate agent.json + embedded main.py before deploy
viksa-agent-validate ./my-agent/

# Or from Python
from viksa_ai.devtools import validate_agent_manifest, AgentValidationError

validate_agent_manifest(manifest_dict)  # raises AgentValidationError

Platform HTTP client (ViksaClient)

Call Viksa REST APIs from scripts, automation, or backends. Distinct from ViksaAuth inside agents (external API keys). Supports JWT, project API keys, and login; base_url is configurable for staging and self-hosted gateways.

Authenticationpy
from viksa_ai import ViksaClient

# JWT (console or prior login)
async with ViksaClient(
    access_token="eyJ...",
    org_id="org-id",
    project_id="project-id",
    base_url="https://api.viksaai.com",  # or staging / self-hosted
) as client:
    me = await client.auth.me()

# Project API key
client = ViksaClient.from_api_key("vk_...", validate=True)

# Email / password
client = await ViksaClient.from_login("[email protected]", "password")

# Environment: VIKSA_API_KEY | VIKSA_ACCESS_TOKEN | VIKSA_EMAIL+VIKSA_PASSWORD
client = ViksaClient.from_env()

REST surface: API reference. Platform sign-in (SSO): Authentication.

Typed API errors

HTTP failures map to exceptions such as ViksaNotFoundError, ViksaValidationError, and ViksaRateLimitError, with parsed FastAPI detail and optional request_id. Retries and JWT refresh are configurable.

Error handlingpy
from viksa_ai import ViksaClient, ViksaNotFoundError, ViksaValidationError

try:
    await client.builder.agents.get("missing")
except ViksaNotFoundError as e:
    print(e.status_code, e.detail_message, e.request_id)
except ViksaValidationError as e:
    print(e.details)

Example agent in the SDK repo

examples/aviation_agent/main.py — multiple @mcp_endpoint handlers with ViksaAuth.require_param for an external API key.

Agents

Creating agents →

Reference

REST API →