Creating agents

Name: ViksaAI
Rating: 4.9 (150 reviews)

From a blank create flow through build, auth, and deploy—aligned with the current app.

Prerequisites

A ViksaAI account with an organization and a project to attach the agent to

Python 3.11+ and async I/O (the worker runs async endpoints)

Core concepts, Cloud vs Secure

1. Open create

In Agents (or Agents Fleet), choose Create agent. You can start from:

Generate with AI — describe the agent; the system proposes files, requirements, inputs and outputs, endpoints, and (when the prompt needs credentials) auth_methods and auth_config that match the product schema.
Start from template or manual — you author or paste code and fill metadata yourself.

Code contract the generator follows

A primary module (commonly main.py) with async def functions.
Each public endpoint function takes exactly one argument, payload: Dict[str, Any], and reads named inputs with payload.get("…").
Functions are decorated with @mcp_endpoint from the injected ViksaAI stub (do not check in a generated ViksaAI.py— the builder injects it).

2. Configure: major steps in the editor

The create / edit experience is organized in sections similar to the following (exact labels can vary slightly by release):

Basics & deployment

Name, description, labels, and Cloud (managed) vs Secure (your Chrona workers).

Endpoints & code

Inputs, outputs, endpoint list, and Python files—often starting from Generate with AI.

Data & access

Mappings, secrets, and (when needed) the Auth step for auth_methods and vault-backed parameters.

Execution & testing

Timeouts, retries, and test invocations (Secure agents may need worker or queue context).

AI guidelines & review

Optional hints for the executor; YAML review before save where enabled.

3. Metadata and deployment

Name and description are used by the executor to choose tools—write them for operators and for the model.

Field	Description
Name	Human title shown in the fleet and in tool lists
Description	What the agent is for; heavily weighted during planning
Cloud vs Secure	Cloud — managed runtime. Secure — run on your Chrona workers.
Labels	Optional tags for search and policy

4. Inputs, outputs, and endpoints

Declare each input with name, type, and help text. Endpoints list which function implements which capability; each endpoint should declare which inputs it reads from the shared payload.

Example: input schema fragment (JSON / form)

{
  "name": "query",
  "type": "str",
  "description": "What to look up",
  "required": true
}

strintfloatboollistdictAny

5. Write Python: async, single payload, decorator

The build pipeline expects the pattern below. Synchronous def handlers with many positional args are a legacy pattern—migrate to a single payload for new work.

main.py (illustrative)

from typing import Any, Dict

from .ViksaAI import mcp_endpoint

@mcp_endpoint(
    description="Check health and return a small status object",
)
async def check_health(payload: Dict[str, Any]) -> Dict[str, Any]:
    name = payload.get("database_name")
    timeout = int(payload.get("timeout", 30))
    # import your client libraries; prefer aio interfaces for I/O
    return {
        "status": "ok",
        "database": name,
        "checked_within_seconds": timeout,
    }

6. Auth and credentials

When a flow needs tokens or passwords, use the Auth tab and the ViksaAuth helpers instead of overloading the generic inputs list. See the dedicated guide: Auth & credentials and Secrets.

7. Requirements

List pip-installable dependencies only. The builder installs them in the agent image and caches layers when possible.

requirements.txt

aiohttp>=3.9.0

8. Build, deploy, test

Build

Validates syntax, resolves imports against your files, installs requirements, and checks that declared endpoints point at real async functions where required.

Deploy

Cloud — the platform takes the run from here; watch build/deploy badges until healthy.
Secure — ensure Chrona is up and queue mapping matches the agent configuration before expecting successful tests.

Best practices

Return JSON-serializable dicts; avoid throwing raw exceptions without translating them to structured errors.
Document each endpoint in the @mcp_endpoint string—planners read it verbatim.
Scope each agent; split unrelated integrations into multiple agents and link them in a project or workforce.