NagentArtefacts
Dev & Technology
Enterprise and White Glove
Company
Convolo AI connects to a Nagent workspace with an API key. Once it is connected, agents can call 7 Convolo AI actions, such as "Create Character", "Get Character Response" and "List Voices". Nothing is enabled on connect: each action is allowed one at a time, and an action with side effects runs or waits for a person according to the agent's level.
Every operation an agent can call against Convolo AI, with input parameters and output schema.
CONVOLO_AI_CREATE_CHARACTERTool to create a new character. Use when you have name, voice type, backstory, and optional actions ready.
Input parameters
Optional list of actions the character can perform.
Name of the character to create.
Background information or story for the character.
Voice type to assign; see Voice List API for available values.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
CONVOLO_AI_EVALUATE_CHARACTEREvaluates a conversation session across 9 quality dimensions (clarity, courtesy, product knowledge, etc.) using AI analysis. Returns structured ratings and feedback. Prerequisites: - A valid session_id from Get Character Response - A character_id from Create Character - Prompt must include \[\[conversation_history\]\] placeholder Note: This API requires Professional Plan or higher access.
Input parameters
Evaluation instructions that MUST include the placeholder \[\[conversation_history\]\]. The conversation history will be automatically fetched and inserted. You can add other placeholders and provide their values via the 'variables' parameter.
Optional key-value pairs for custom variables referenced in your prompt (e.g., \[\[customer_name\]\], \[\[product\]\]). Do NOT include \[\[conversation_history\]\] here—it's automatically provided.
The ID of the conversation session to evaluate. Obtain this from a Get Character Response action.
The ID of the character that will perform the evaluation. Obtain this from a Create Character action.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
CONVOLO_AI_GENERATE_STARTER_CONVERSATIONGenerates AI-powered conversation starter suggestions for a character. This tool creates contextually relevant opening lines or follow-up dialogue suggestions that can be used to initiate or continue conversations with AI characters. Perfect for chatbots, virtual assistants, game NPCs, or interactive storytelling applications. Use this when you need: - Opening conversation starters for a new interaction (sessionId="-1") - Follow-up suggestions based on an ongoing conversation (provide existing sessionId) - Multiple conversation options to choose from
Input parameters
The unique identifier of the character for which to generate conversation starters. Obtain this from the Create Character action.
The session identifier for context-aware suggestions. Use "-1" to generate opening conversation starters for a new session, or provide an existing session ID for follow-up dialogue suggestions.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
CONVOLO_AI_GET_CHARACTER_RESPONSETool to generate a response from a ConvAI character based on text or audio input. Use when needing a text or voice reply in an ongoing session.
Input parameters
Mono WAV audio file bytes; provide only if not sending userText
ID of the character to interact with
Enable SSE streaming; "True" or "False"
User text input; provide only if not sending audio
Session identifier; use "-1" to start a new session
Sample rate of the uploaded audio in Hz
Whether to return response audio
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
CONVOLO_AI_LIST_VOICESTool to retrieve the list of available voice types. Use when selecting voices before generating speech.
Input parameters
Override the Accept header if provided.
Override the Content-Type header if provided.
If true, use https://api.convai.com as base URL instead of default.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
CONVOLO_AI_SET_CORE_AI_SETTINGSUpdates the core AI settings (model and/or temperature) for an existing Convai character. Use this action to: - Switch the AI model powering a character (e.g., from GPT-4o to Claude) - Adjust response creativity via temperature parameter (0.0=deterministic, 1.0=creative) - Fine-tune character behavior without recreating the character Prerequisites: Requires a valid charID from a previously created character. At least one of model_group_name or temperature must be specified.
Input parameters
The unique identifier (charID) of the character to update. Obtain this from CREATE_CHARACTER or character listing endpoints.
Controls response randomness/creativity (0.0-1.0). Lower values (0.0-0.3) make responses more focused and deterministic; higher values (0.7-1.0) increase creativity and variation. Default behavior maintained if not specified. Optional - provide only when adjusting.
AI language model to use for this character. Choose based on desired capabilities: GPT models for general use, Claude for nuanced conversations, Gemini for multimodal, Llama for open-source. Optional - provide only when changing the model.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
CONVOLO_AI_UPLOAD_KNOWLEDGE_BANKTool to upload a knowledge bank file. Use when you have a file ready to add to Convolo AI's knowledge bank (Enterprise plan only).
Input parameters
Raw bytes of the knowledge bank file to upload
Name of the file being uploaded
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
Agents can call 7 Convolo AI actions on Nagent, including "Create Character", "Get Character Response" and "List Voices". Create Character: Create a new character. Each action is listed on this page with its input parameters and its output.
Convolo AI connects with an API key, under your workspace's own connection. Nothing is enabled on connect: each action is allowed one at a time and can be scoped to the agents that need it.
Create Character takes 3 required inputs: charName, backstory and voiceType. It also takes 1 optional input: actions. It returns data, error and successful.