Python SDK

Package viksa-ai on PyPI — same runtime the platform injects as ViksaAI.py, plus API client and dev tooling.

Install

Terminal
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)

Use this when authoring agents locally or in CI. In the dashboard editor, the platform injects equivalent symbols from ViksaAI.py — do not check that file into git.

main.py (local / package import)
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}
Platform editor
# In the platform editor, import from the injected stub instead:
from .ViksaAI import mcp_endpoint, ViksaAuth, ViksaAuthError

# builder-service and chat-service inject ViksaAI.py from the viksa-ai package.
# Do not commit ViksaAI.py in your agent 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 push
# 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.

Authentication
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 handling
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 →