Quickstart Guide

Viksa AI processes headless requests in a closed loop. Every goal follows a secure three-step cycle:

1. 1

   Ingest APIs or Python Agents

   Viksa AI allows you to ingest OpenAPI (Swagger) specifications directly to register virtual tools. Alternatively, write Python agents using the public SDK with the @mcp_endpoint decorator:

   from typing import Any, Dict
   
   
   from viksa_ai.runtime import mcp_endpoint
   
   @mcp_endpoint(description="Greet someone by name from the payload")
   async def greet(payload: Dict[str, Any]) -> Dict[str, Any]:
       name = payload.get("name") or "there"
       return {"message": f"Hello, {name}! Welcome to Viksa AI."}
   

   See the Python SDK guide or Headless API Fleet configuration.

2. 2

   Configure User Auth KMS

   Secure customer-facing credentials by configuring your Key Management Service (AWS KMS, GCP KMS, or Azure Key Vault) key path. This ensures all user access tokens or database keys are stored encrypted and decrypted only inside VPC workers.

3. 3

   Link Channel Connectors

   Connect your headless workspace to Slack, WhatsApp, Microsoft Teams, Telegram, or Instagram via shared HTTPS webhooks. Replace visual menus (GUI) and terminal scripts (CLI) with headless agent execution.

4. 4

   Trigger Headless Execution

   Users can trigger runs directly from their native messaging app (e.g. Slack or WhatsApp) using natural language. Viksa binds their identity, decrypts keys via KMS, resolves dependencies, and plans execution loops.

   User: "Greet John and check if our servers are healthy."
   
   Think → Act → Observe:
     1. hello_agent.greet(name="John")
     2. server_health.check_health()

5. 5

   Trigger Headless API Execution

   To execute workflows programmatically from alerts, pipelines, or your custom app, call the endpoint execution gateway POST payload:

   {
     "event": "incident.opened",
     "severity": "high",
     "service": "payments-api",
     "goal": "Investigate elevated error rate and restart unhealthy pods if needed"
   }

Now that you have deployed your first agentic loop, explore advanced configuration topics: