Skip to content

Agents

The Agents page in PinionAI Studio is the control center for creating, configuring, and managing your AI Agents. These agents are the core cognitive bots that process user intent, run rules and actions, utilize tools/APIs/MCPs, and generate responses based on their defined setups.

Permissions & Prerequisites

Access to the Agents page and its configuration tools is restricted by user roles:

  • Required Roles: Users must have owner, admin, editor, or agent_edit permissions.
  • Account Context: Because agents are always scoped to an account, you must select an Account from the sidebar before you can add, view, or modify agents.

Page Overview

The page provides a complete toolkit for managing the agent lifecycle: - Variable & Schema Utilities: Fast access buttons to create variables or look up system names on the fly. - Agent Builder (New Agent): Comprehensive form to define the agent's identity, design, prompts, fallback mechanisms, transfer channels, and speech configs. - Agent Duplication Modal: Instant cloning of existing agents with fully mapped fields. - Existing Agents Panel: An expandable, prioritized listing of your agents, highlighting the active selection, status, and custom settings with inline management actions.

Inline Utility Actions

To keep developers from having to navigate away mid-configuration, the New Agent and Edit Agent headers include two quick-action tools:

  1. Add Variable (:material/variables:): Opens an overlay dialog to create and define a new system or session variable immediately.
  2. Lookup Names (:material/search:): Opens a searchable lookup dialog to find the exact names of registered Prompts, Variables, Intents, or Connectors.

Creating a New AI Agent

Expand the New Agent section to configure a new agent using the following fields:

1. Identity & Visuals

  • Agent Name: A unique, system-level alphanumeric identifier for the agent (e.g., sales_agent_v1).
  • Accent Color: The primary theme color used in the customer-facing chat UI (options: blue, green, orange, red, violet, gray, rainbow).
  • Agent Title: The display name shown in the customer chat interface (e.g., PinionAI Support).
  • Agent Subtitle: A descriptive tagline shown under the title (e.g., Ask me anything about your billing).
  • Agent Status: Toggle to set the agent as Active (enabled) or Inactive (disabled).
  • User Image Path: Public URL to the avatar representing the human user in the chat view.
  • Assistant Image Path: Public URL to the avatar representing the AI agent.

2. Prompts, Logic & Fallbacks

  • Agent Description: A high-level prompt description that helps focus the LLM on the agent's scope or focus.
  • Agent Knowledge: Standard reference knowledge or groundings specific to this agent.
  • Start Statement: The initial welcome message displayed when a user begins a chat (e.g., Hello! How can I help you today?). This supports dynamic variables like {{var.noInputIntentNameList}}.
  • Start Prompt: Selects the agent's beginning classification prompt (classification type) used to route user messages.
  • Default Intent: The fallback intent used when the LLM cannot confidently match the user's input to any specific configured intent.

3. Voice & Audio Integration

Integrate Speech-to-Text and Text-to-Speech audio profiles to support hands-free voice-to-voice testing: - Speech-to-Text (STT) Configuration: Selects an active audio transcription engine (e.g., a local Whisper server or Google Cloud STT) to process incoming voice recordings. - Text-to-Speech (TTS) Configuration: Selects an active voice synthesis engine (e.g., ElevenLabs or gTTS) to read AI responses aloud.

4. Connection & Form Settings

  • Default Connector: Selects a Google Cloud Service Account connector used for backend authentication or groundings when the studio is run outside of GCP.
  • Form Domain: The hosting server for secure AI-driven dynamic forms (defaults to https://f.pinionai.com).

5. Live Agent Transfer Settings

Define handoff paths for transferring customer chats to human agents: - Allow Transfer: A toggle enabling or disabling live agent escalation. - Transfer Passkey: A toggle requiring passkey verification prior to transferring the conversation. - Transfer Types: Multi-select of allowed communication channels for the handoff (chat, callback, voice). - Transfer Phone: The support phone number displayed for direct call-in or routing.

Duplicating an Agent

PinionAI Studio supports deep-cloning to speed up multi-agent testing:

  1. Click the Duplicate (:material/content_copy:) icon next to any agent in the list.
  2. A dialog will open prompting you for a New Agent Name (defaults to <original_name> copy).
  3. Upon submission, the database clones all original parameters, generates a brand new unique uid, maps complex fields like JSON data and array parameters (e.g., transfer_types), and creates a separate, independent replica.

Listing, Selecting & Active Sessions

All agents configured under your selected account are listed. * Selected Marker: The active agent being edited or tested is marked with a :star: SELECTED AGENT label. Selecting an agent scopes pages like Intents, Prompts, and Variables to show only resources relevant to that specific agent. * Selective Filtering: Expand any agent row to view its entire configuration parameter set, including UID, voice configs, and connection profiles. * Quick Select (:material/check:): Clicking the checkmark button next to an agent immediately sets it as the active session agent and updates your last-saved context.

Deleting an Agent (Automatic Cascading Cleanup)

To prevent broken links, broken UI cards, or orphaned references when an agent is removed, PinionAI Studio executes an automated 16-table cascading cleanup:

When you click Delete (:material/delete:): 1. The system deletes all active Sessions associated with the agent's unique UID. 2. The system deletes all registered Versions linked to that agent's UID. 3. The system identifies 16 core resource tables where this agent might be referenced in an array of assigned agents, and automatically removes the agent's name (agent_name) from those arrays. These tables include: * prompts (prompt_agents) * intents (intent_agents) * variables (variable_agents) * tools (tool_agents) * apis (api_agents) * scripts (script_agents) * parsers (parser_agents) * mergers (merger_agents) * deliveries (delivery_agents) * actions (action_agents) * connectors (connector_agents) * rules (rule_agents) * iframes (iframe_agents) * files (file_agents) * stores (store_agents) * mcps (mcp_agents) 4. Finally, the agent's primary record is deleted from the agents table. If any step fails, the entire transaction is rolled back safely.