Endpoints

What are Endpoints?

Endpoints are the callable entry points into your agent. Each endpoint maps to a Python function that can be invoked during execution. An agent can have multiple endpoints, each performing a different action.

Python: @mcp_endpoint

Each callable function in main.py should be async, accept exactly one argument payload: Dict[str, Any], and use the @mcp_endpoint(description="...") decorator from viksa_ai.runtime. The description is shown to the executor and validated by viksa-agent-validate. See Python SDK and Creating agents.

Endpoint Structure

Endpoint Naming

Endpoints are referenced using the format:

For example, if your agent has alias db_agent and you have a function health_check in agent.py, the full endpoint would be: db_agent.agent.health_check

Input Mapping

Endpoints reference global agent inputs. When configuring an endpoint, you specify which inputs the function requires:

{
    "name": "query",
    "module": "agent",
    "description": "Execute a SQL query on the database",
    "inputs": ["database_name", "query_string"],
    "outputs": ["result"],
    "timeout": 60
}

Enabling and Disabling Endpoints

You can enable or disable individual endpoints without modifying code:

User-scoped inputs (invoker binding)

For Channel Hub and other Volt connectors, identity fields such as user_id and user_email must not be filled by the AI. Mark them source: invoker in agent metadata; the platform injects values from your project user directory at dispatch.

{
  "name": "user_id",
  "type": "string",
  "source": "invoker",
  "bind": "profile.acme_user_id"
}

Using Secrets

Endpoints can reference secrets stored in the Vault. Secrets are injected as environment variables at runtime:

import os

def query_database(query_string: str) -> dict:
    # Secret is injected as environment variable
    db_password = os.environ.get("DB_PASSWORD")
    
    # Use the secret in your code
    connection = connect(password=db_password)
    ...

Best Practices