> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Simula una conversazione POST https://api.elevenlabs.io/v1/convai/agents/{agent_id}/simulate-conversation Content-Type: application/json Deprecato. Questo endpoint verrà rimosso il 31 ottobre 2026. Usa gli endpoint `/v1/convai/agent-testing/create` e `/v1/convai/agents/:agent_id/run-tests` per creare ed eseguire simulazioni. Esegui una conversazione tra l'agente e un utente simulato. Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/simulate-conversation ## Servers - `https://api.elevenlabs.io` (Production, default) - `https://api.us.elevenlabs.io` (Production US) - `https://api.eu.residency.elevenlabs.io` (Production EU) - `https://api.in.residency.elevenlabs.io` (Production India) - `https://api.sg.residency.elevenlabs.io` (Production Singapore) ## Request ### Path parameters - `agent_id` (string, required) — L'ID di un agente. Viene restituito alla creazione dell'agente. ### Body (application/json) This endpoint expects an object. - `simulation_specification` (ConversationSimulationSpecification, required) — Una specifica che descrive in dettaglio come simulare la conversazione - `extra_evaluation_criteria` (list of PromptEvaluationCriteria, optional) — Un elenco di criteri di valutazione da testare. - `new_turns_limit` (integer, optional, default: 100) — Numero massimo di nuovi turni da generare nella simulazione della conversazione ## Response ### 200 Risposta riuscita - `simulated_conversation` (list of ConversationHistoryTranscriptResponseModel, required) - `analysis` (ConversationHistoryAnalysisCommonModel, required) ## Errors ### 422 Agents Simulate Conversation Request Unprocessable Entity Error Errore di convalida - `detail` (list of ValidationError, optional) ## Types ### ConversationSimulationSpecification Una specifica che verrà usata per simulare una conversazione tra un agente e un utente IA. - `simulated_user_config` (AgentConfig, required) - `tool_mock_config` (map from string to ToolMockConfig, optional) - `partial_conversation_history` (list of ConversationHistoryTranscriptCommonModelInput, optional) — Una cronologia parziale della conversazione da cui avviare la simulazione. Se è vuota, la simulazione inizia da zero. - `dynamic_variables` (map from string to any, optional) ### PromptEvaluationCriteria Una valutazione che usa la trascrizione e un prompt per una risposta sì/no relativa al raggiungimento dell'obiettivo - `id` (string, required) — L'identificatore univoco dei criteri di valutazione - `name` (string, required) - `conversation_goal_prompt` (string, required) — Il prompt che l'agente deve usare per valutare la conversazione - `type` ("prompt", optional) — Il tipo di criteri di valutazione - `use_knowledge_base` (boolean, optional, default: false) — Indica se usare la knowledge base dell'agente durante la valutazione del prompt. - `scope` (enum, optional, default: conversation) — L'ambito del contesto della trascrizione usato per valutare questo criterio. 'conversation' usa la trascrizione completa; 'agent' usa solo la parte in cui era attivo l'agente che l'ha definito. - Allowed values: `conversation`, `agent` - `llm` (enum, optional) — Modello LLM da utilizzare per questo criterio di valutazione. Se non impostato, utilizza il valore predefinito analysis_llm dell'agente. - Allowed values: `gpt-4o-mini`, `gpt-4o`, `gpt-4`, `gpt-4-turbo`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, `gpt-5`, `gpt-5.1`, `gpt-5.2`, `gpt-5.2-chat-latest`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-6-astra`, `gpt-6-sol`, `gpt-6-luna`, `gpt-6.1-sol`, `gpt-5-mini`, `gpt-5-nano`, `gpt-3.5-turbo`, `gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-2.0-flash`, `gemini-2.0-flash-lite`, `gemini-2.5-flash-lite`, `gemini-2.5-flash`, `gemini-3-pro-preview`, `gemini-3-flash-preview`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3.1-flash-lite`, `gemini-3.5-flash`, `gemini-3.5-flash-lite`, `gemini-3.6-flash`, `gemini-3.7-flash`, `gemini-3.8-flash`, `claude-sonnet-4-5`, `claude-opus-4-7`, `claude-opus-4-8`, `claude-opus-5`, `claude-opus-5-5`, `claude-sonnet-4-6`, `claude-sonnet-5`, `claude-sonnet-5-5`, `claude-sonnet-4`, `claude-haiku-4-5`, `claude-3-7-sonnet`, `claude-3-5-sonnet`, `claude-3-5-sonnet-v1`, `claude-3-haiku`, `grok-beta`, `custom-llm`, `qwen3-4b`, `qwen3-30b-a3b`, `qwen36-35b-a3b`, `qwen35-397b-a17b`, `gpt-oss-20b`, `gpt-oss-120b`, `glm-45-air-fp8`, `glm-52`, `deepseek-v41-flash`, `gemini-2.5-flash-preview-09-2025`, `gemini-2.5-flash-lite-preview-09-2025`, `gemini-2.5-flash-preview-05-20`, `gemini-2.5-flash-preview-04-17`, `gemini-2.5-flash-lite-preview-06-17`, `gemini-2.0-flash-lite-001`, `gemini-2.0-flash-001`, `gemini-1.5-flash-002`, `gemini-1.5-flash-001`, `gemini-1.5-pro-002`, `gemini-1.5-pro-001`, `claude-sonnet-4@20250514`, `claude-sonnet-4-5@20250929`, `claude-haiku-4-5@20251001`, `claude-3-7-sonnet@20250219`, `claude-3-5-sonnet@20240620`, `claude-3-5-sonnet-v2@20241022`, `claude-3-haiku@20240307`, `gpt-5-2025-08-07`, `gpt-5.1-2025-11-13`, `gpt-5.2-2025-12-11`, `gpt-5.4-2026-03-05`, `gpt-5.4-mini-2026-03-17`, `gpt-5.4-nano-2026-03-17`, `gpt-5.5-2026-04-23`, `gpt-5-mini-2025-08-07`, `gpt-5-nano-2025-08-07`, `gpt-4.1-2025-04-14`, `gpt-4.1-mini-2025-04-14`, `gpt-4.1-nano-2025-04-14`, `gpt-4o-mini-2024-07-18`, `gpt-4o-2024-11-20`, `gpt-4o-2024-08-06`, `gpt-4o-2024-05-13`, `gpt-4-0613`, `gpt-4-0314`, `gpt-4-turbo-2024-04-09`, `gpt-3.5-turbo-0125`, `gpt-3.5-turbo-1106`, `watt-tool-8b`, `watt-tool-70b` - `scoring_mode` (enum, optional, default: binary) — Come viene valutato questo criterio. 'binary' restituisce successo/errore/sconosciuto. 'numeric_uniform' restituisce un numero nella scala [0, max_score], normalizzato nella percentuale aggregata di successo della conversazione. - Allowed values: `binary`, `numeric_uniform` - `max_score` (integer, optional, default: 100) — Valore massimo della scala di punteggio numerica (il minimo è sempre 0). Utilizzato solo quando scoring_mode è 'numeric_uniform'. - `score_instructions` (string, optional) — Istruzioni facoltative in testo libero che descrivono come assegnare i valori nella scala numerica. Usate solo quando scoring_mode è 'numeric_uniform'. ### ConversationHistoryTranscriptResponseModel - `role` (enum, required) - Allowed values: `user`, `agent` - `time_in_call_secs` (integer, required) - `agent_metadata` (AgentMetadata, optional) - `message` (string, optional) - `multivoice_message` (ConversationHistoryMultivoiceMessageModel, optional) — Rappresenta un messaggio di un agente multivoce. - `tool_calls` (list of ConversationHistoryTranscriptToolCallCommonModelOutput, optional) - `tool_results` (list of ConversationHistoryTranscriptResponseModelToolResultsItem, optional) - `feedback` (UserFeedback, optional) - `llm_override` (string, optional) - `producing_llm` (string, optional) - `conversation_turn_metrics` (ConversationTurnMetrics, optional) - `rag_retrieval_info` (RagRetrievalInfo, optional) - `llm_usage` (LlmUsageOutput, optional) - `interrupted` (boolean, optional, default: false) - `ignored_as_backchannel` (boolean, optional, default: false) - `platform_event` (enum, optional) - Allowed values: `user_turn_timeout`, `skip_turn_wait_elapsed` - `original_message` (string, optional) - `reasoning` (list of ConversationReasoningModel, optional) - `source_medium` (enum, optional) - Allowed values: `audio`, `dtmf`, `text`, `image`, `file` - `source_event_id` (integer, optional) - `used_static_kb_document_ids` (list of string, optional) - `user_identifier` (string, optional) - `id` (string, optional) - `triggered_guardrails` (list of TriggeredGuardrailCommonModel, optional) - `file_input` (ConversationHistoryTranscriptFileInputResponseModel, optional) — Deprecato: il primo allegato in questo turno. Usa `file_inputs` per visualizzare tutti gli allegati. - `file_inputs` (list of ConversationHistoryTranscriptFileInputResponseModel, optional) — Tutti i file allegati a questo turno, nell'ordine in cui l'utente li ha allegati. - `contextual_update_info` (ContextualUpdateInfo, optional) - `reasoned` (boolean, optional, default: false) ### ConversationHistoryAnalysisCommonModel - `call_successful` (enum, required) - Allowed values: `success`, `failure`, `unknown` - `transcript_summary` (string, required) - `evaluation_criteria_results` (map from string to ConversationHistoryEvaluationCriteriaResultCommonModel, optional) - `data_collection_results` (map from string to DataCollectionResultCommonModel, optional) - `evaluation_criteria_results_list` (list of ConversationHistoryEvaluationCriteriaResultCommonModel, optional) - `data_collection_results_list` (list of DataCollectionResultCommonModel, optional) - `call_success_score` (double, optional) - `call_summary_title` (string, optional) - `scoped` (list of ScopedAnalysisResult, optional) ### ValidationError - `loc` (list of ValidationErrorLocItem, required) - `msg` (string, required) - `type` (string, required) ### AgentConfig - `first_message` (string, optional, default: ) — Se non è vuoto, è il primo messaggio che l'agente pronuncerà. Se è vuoto, l'agente attende che l'utente avvii la conversazione. - `language` (string, optional, default: en) — Lingua dell'agente, usata per ASR e TTS - `hinglish_mode` (boolean, optional, default: false) — Quando è abilitata e la lingua è l'hindi, l'agente risponderà in hinglish - `dynamic_variables` (any, optional) - `disable_first_message_interruptions` (boolean, optional, default: false) — Se true, l'utente non potrà interrompere l'agente durante la riproduzione del primo messaggio. - `max_conversation_duration_message` (string, optional, default: ) — Se non è vuoto, è il messaggio che l'agente invierà al raggiungimento della durata massima della conversazione. - `text_behavior_overrides` (map from string to BehaviorOverride, optional) — Sostituzioni del comportamento di risposta per canale nelle conversazioni testuali. Se non impostate, si applicano le impostazioni predefinite integrate del canale. - `prompt` (PromptAgentApiModelOutput, optional) — Il prompt per l'agente ### ToolMockConfig - `default_return_value` (string, optional, default: Tool Called.) - `default_is_error` (boolean, optional, default: false) ### ConversationHistoryTranscriptCommonModelInput - `role` (enum, required) - Allowed values: `user`, `agent` - `time_in_call_secs` (integer, required) - `agent_metadata` (AgentMetadata, optional) - `message` (string, optional) - `multivoice_message` (ConversationHistoryMultivoiceMessageModel, optional) — Rappresenta un messaggio di un agente multivoce. - `tool_calls` (list of ConversationHistoryTranscriptToolCallCommonModelInput, optional) - `tool_results` (list of ConversationHistoryTranscriptCommonModelInputToolResultsItem, optional) - `feedback` (UserFeedback, optional) - `llm_override` (string, optional) - `producing_llm` (string, optional) - `conversation_turn_metrics` (ConversationTurnMetrics, optional) - `rag_retrieval_info` (RagRetrievalInfo, optional) - `llm_usage` (LlmUsageInput, optional) - `interrupted` (boolean, optional, default: false) - `ignored_as_backchannel` (boolean, optional, default: false) - `platform_event` (enum, optional) - Allowed values: `user_turn_timeout`, `skip_turn_wait_elapsed` - `original_message` (string, optional) - `reasoning` (list of ConversationReasoningModel, optional) - `source_medium` (enum, optional) - Allowed values: `audio`, `dtmf`, `text`, `image`, `file` - `source_event_id` (integer, optional) - `used_static_kb_document_ids` (list of string, optional) - `user_identifier` (string, optional) - `id` (string, optional) - `triggered_guardrails` (list of TriggeredGuardrailCommonModel, optional) ### AgentMetadata - `agent_id` (string, required) - `branch_id` (string, optional) - `workflow_node_id` (string, optional) - `version_id` (string, optional) ### ConversationHistoryMultivoiceMessageModel Rappresenta un messaggio di un agente multivoce. - `parts` (list of ConversationHistoryMultivoiceMessagePartModel, required) ### ConversationHistoryTranscriptToolCallCommonModelOutput - `request_id` (string, required) - `tool_name` (string, required) - `params_as_json` (string, required) - `tool_has_been_called` (boolean, required) - `type` (enum, optional) - Allowed values: `system`, `webhook`, `client`, `mcp`, `workflow`, `api_integration_webhook`, `api_integration_mcp`, `smb` - `tool_details` (ConversationHistoryTranscriptToolCallCommonModelOutputToolDetails, optional) ### ConversationHistoryTranscriptResponseModelToolResultsItem ### UserFeedback - `score` (enum, required) - Allowed values: `like`, `dislike` - `time_in_call_secs` (integer, required) ### ConversationTurnMetrics - `metrics` (map from string to MetricRecord, optional) - `convai_asr_provider` (string, optional) - `convai_tts_model` (string, optional) - `convai_tts_cascade` (string, optional) ### RagRetrievalInfo - `chunks` (list of RagChunkMetadata, required) - `embedding_model` (enum, required, default: e5_mistral_7b_instruct) - Allowed values: `e5_mistral_7b_instruct`, `multilingual_e5_large_instruct` - `retrieval_query` (string, required) - `rag_latency_secs` (double, required) - `used_chunk_ids` (list of string, optional) ### LlmUsageOutput - `model_usage` (map from string to LlmInputOutputTokensUsage, optional) ### ConversationReasoningModel - `summary` (string, optional) - `provider_redact` (boolean, optional, default: false) ### TriggeredGuardrailCommonModel - `guardrail_type` (enum, required) - Allowed values: `custom`, `prompt_injection`, `self_harm_intent`, `violence_graphic`, `sexual`, `violence`, `harassment`, `sexual_minors`, `self_harm`, `self_harm_instructions`, `harassment_threatening`, `hate`, `hate_threatening`, `profanity`, `religion_or_politics`, `medical_and_legal`, `guardrail` - `guardrail_name` (string, optional) ### ConversationHistoryTranscriptFileInputResponseModel - `file_id` (string, required) - `original_filename` (string, required) - `mime_type` (string, required) - `file_url` (string, required) ### ContextualUpdateInfo - `context_id` (string, required) — Identificatore fornito dal client che raggruppa gli aggiornamenti contestuali correlati. - `is_superseded` (boolean, optional, default: false) — True quando questo aggiornamento contestuale è stato sostituito da un aggiornamento più recente con lo stesso context_id. ### ConversationHistoryEvaluationCriteriaResultCommonModel - `criteria_id` (string, required) - `result` (enum, required) - Allowed values: `success`, `failure`, `unknown` - `rationale` (string, required) - `scoring_mode` (enum, optional, default: binary) - Allowed values: `binary`, `numeric_uniform` - `score` (integer, optional) - `max_score` (integer, optional) ### DataCollectionResultCommonModel - `data_collection_id` (string, required) - `rationale` (string, required) - `name` (string, optional) - `value` (any, optional) - `json_schema` (LiteralJsonSchemaProperty, optional) — Proprietà dello schema per tipi JSON letterali. IMPORTANTE: puoi impostare UN SOLO dei seguenti campi: description (il LLM fornisce il valore), dynamic_variable (valore da variabile), is_system_provided (il sistema fornisce il valore), constant_value (valore fisso) oppure is_omitted (il parametro viene omesso). Sono mutuamente esclusivi. ### ScopedAnalysisResult - `scope` (enum, required, default: conversation) — L'ambito dell'analisi. 'conversation' usa la trascrizione completa; 'agent' usa solo la parte in cui era attivo l'agente che l'ha definito. - Allowed values: `conversation`, `agent` - `source_agent_id` (string, required) - `successful` (enum, required) - Allowed values: `success`, `failure`, `unknown` - `source_branch_id` (string, optional) — Branch dell'agente per questo blocco con ambito; distingue gli agent_id ripetuti. - `evaluation_criteria_results` (map from string to ConversationHistoryEvaluationCriteriaResultCommonModel, optional) - `data_collection_results` (map from string to DataCollectionResultCommonModel, optional) - `success_score` (double, optional) ### ValidationErrorLocItem ### BehaviorOverride - `verbosity` (enum, optional) — Override della verbosità. Se non impostato, viene applicato il valore predefinito sottostante. - Allowed values: `auto`, `concise`, `thorough` - `output_format` (enum, optional) — Override del formato di output. Se non impostato, si applica il valore predefinito sottostante. - Allowed values: `mp3_22050_32`, `mp3_44100_32`, `mp3_44100_64`, `mp3_44100_96`, `mp3_44100_128`, `mp3_44100_192`, `pcm_16000`, `pcm_22050`, `pcm_24000`, `pcm_44100`, `ulaw_8000` - `interaction_budget` (enum, optional) — Override del budget di interazione. Se non impostato, si applica il valore predefinito sottostante. - Allowed values: `realtime`, `5_minutes`, `10_minutes`, `1_hour` ### PromptAgentApiModelOutput - `prompt` (string, optional, default: ) — Il prompt per l'agente - `llm` (enum, optional) — L'LLM da interrogare con il prompt e la cronologia della chat. Se utilizzi la residenza dei dati, l'LLM deve essere supportato nell'ambiente di residenza dei dati. - Allowed values: `gpt-4o-mini`, `gpt-4o`, `gpt-4`, `gpt-4-turbo`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, `gpt-5`, `gpt-5.1`, `gpt-5.2`, `gpt-5.2-chat-latest`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-6-astra`, `gpt-6-sol`, `gpt-6-luna`, `gpt-6.1-sol`, `gpt-5-mini`, `gpt-5-nano`, `gpt-3.5-turbo`, `gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-2.0-flash`, `gemini-2.0-flash-lite`, `gemini-2.5-flash-lite`, `gemini-2.5-flash`, `gemini-3-pro-preview`, `gemini-3-flash-preview`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3.1-flash-lite`, `gemini-3.5-flash`, `gemini-3.5-flash-lite`, `gemini-3.6-flash`, `gemini-3.7-flash`, `gemini-3.8-flash`, `claude-sonnet-4-5`, `claude-opus-4-7`, `claude-opus-4-8`, `claude-opus-5`, `claude-opus-5-5`, `claude-sonnet-4-6`, `claude-sonnet-5`, `claude-sonnet-5-5`, `claude-sonnet-4`, `claude-haiku-4-5`, `claude-3-7-sonnet`, `claude-3-5-sonnet`, `claude-3-5-sonnet-v1`, `claude-3-haiku`, `grok-beta`, `custom-llm`, `qwen3-4b`, `qwen3-30b-a3b`, `qwen36-35b-a3b`, `qwen35-397b-a17b`, `gpt-oss-20b`, `gpt-oss-120b`, `glm-45-air-fp8`, `glm-52`, `deepseek-v41-flash`, `gemini-2.5-flash-preview-09-2025`, `gemini-2.5-flash-lite-preview-09-2025`, `gemini-2.5-flash-preview-05-20`, `gemini-2.5-flash-preview-04-17`, `gemini-2.5-flash-lite-preview-06-17`, `gemini-2.0-flash-lite-001`, `gemini-2.0-flash-001`, `gemini-1.5-flash-002`, `gemini-1.5-flash-001`, `gemini-1.5-pro-002`, `gemini-1.5-pro-001`, `claude-sonnet-4@20250514`, `claude-sonnet-4-5@20250929`, `claude-haiku-4-5@20251001`, `claude-3-7-sonnet@20250219`, `claude-3-5-sonnet@20240620`, `claude-3-5-sonnet-v2@20241022`, `claude-3-haiku@20240307`, `gpt-5-2025-08-07`, `gpt-5.1-2025-11-13`, `gpt-5.2-2025-12-11`, `gpt-5.4-2026-03-05`, `gpt-5.4-mini-2026-03-17`, `gpt-5.4-nano-2026-03-17`, `gpt-5.5-2026-04-23`, `gpt-5-mini-2025-08-07`, `gpt-5-nano-2025-08-07`, `gpt-4.1-2025-04-14`, `gpt-4.1-mini-2025-04-14`, `gpt-4.1-nano-2025-04-14`, `gpt-4o-mini-2024-07-18`, `gpt-4o-2024-11-20`, `gpt-4o-2024-08-06`, `gpt-4o-2024-05-13`, `gpt-4-0613`, `gpt-4-0314`, `gpt-4-turbo-2024-04-09`, `gpt-3.5-turbo-0125`, `gpt-3.5-turbo-1106`, `watt-tool-8b`, `watt-tool-70b` - `reasoning_effort` (enum, optional) — Livello di ragionamento del modello. Disponibile solo per alcuni modelli. - Allowed values: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` - `thinking_budget` (integer, optional) — Numero massimo di token utilizzati per il ragionamento. Usa 0 per disattivarlo, se supportato dal modello. - `enable_reasoning_summary` (boolean, optional, default: false) — Abilita i riepiloghi del ragionamento del modello. Se disabilitati, quando possibile non richiediamo riepiloghi al provider per un TTFB più rapido. Non compatibile con ZRM. - `temperature` (double, optional) — La temperatura per l'LLM. Il valore predefinito è 0. Imposta null per omettere completamente il parametro dalla richiesta all'LLM, utile per LLM personalizzati che rifiutano il campo della temperatura. - `max_tokens` (integer, optional, default: -1) — Se maggiore di 0, numero massimo di token che l'LLM può prevedere - `tool_ids` (list of string, optional) — Un elenco di ID degli strumenti usati dall'agente. - `built_in_tools` (BuiltInToolsOutput, optional) — Strumenti di sistema integrati da usare con l'agente - `enable_parallel_tool_calls` (boolean, optional, default: true) — Abilita le chiamate parallele agli strumenti. Se abilitata, l'agente può eseguire più strumenti in parallelo in un singolo turno. Non supportata da tutti i modelli. - `mcp_server_ids` (list of string, optional) — Un elenco di ID dei server MCP da usare con l'agente - `native_mcp_server_ids` (list of string, optional) — Un elenco di ID dei server MCP nativi da usare con l'agente - `knowledge_base` (list of KnowledgeBaseLocator, optional) — Un elenco di knowledge base da usare con l'agente - `custom_llm` (CustomLlm, optional) — Definizione di un LLM personalizzato se il campo LLM è impostato su 'CUSTOM_LLM' - `ignore_default_personality` (boolean, optional) — Indica se rimuovere le righe di personalità predefinite dal prompt di sistema - `rag` (RagConfigOutput, optional) — Configurazione per RAG - `timezone` (string, optional) — Fuso orario per visualizzare l'ora corrente nel prompt di sistema. Se impostato, l'ora corrente verrà inclusa nel prompt di sistema usando questo fuso orario. Deve essere un nome di fuso orario valido (ad es. 'America/New_York', 'Europe/London', 'UTC'). È consigliato per risposte accurate basate sull'orario; senza questa impostazione, l'agente non conosce la data e l'ora correnti, a meno che non vengano fornite tramite variabili dinamiche o strumenti, e potrebbe quindi fare riferimenti temporali errati o allucinati. - `backup_llm_config` (PromptAgentApiModelOutputBackupLlmConfig, optional) — Configurazione della cascata di LLM di backup. Può essere disabilitata, usare le impostazioni predefinite del sistema o specificare un ordine personalizzato. - `cascade_timeout_seconds` (double, optional, default: 4) — Tempo in secondi prima di passare all'LLM di backup. Deve essere compreso tra 2 e 15 secondi. - `tools` (list of PromptAgentApiModelOutputToolsItem, optional, deprecated) — Un elenco di strumenti che l'agente può usare durante la conversazione; usa invece tool_ids. ### ConversationHistoryTranscriptToolCallCommonModelInput - `request_id` (string, required) - `tool_name` (string, required) - `params_as_json` (string, required) - `tool_has_been_called` (boolean, required) - `type` (enum, optional) - Allowed values: `system`, `webhook`, `client`, `mcp`, `workflow`, `api_integration_webhook`, `api_integration_mcp`, `smb` - `tool_details` (ConversationHistoryTranscriptToolCallCommonModelInputToolDetails, optional) ### ConversationHistoryTranscriptCommonModelInputToolResultsItem ### LlmUsageInput - `model_usage` (map from string to LlmInputOutputTokensUsage, optional) ### ConversationHistoryMultivoiceMessagePartModel Rappresenta una singola parte vocale di un messaggio multivoce. - `text` (string, required) - `voice_label` (string, optional) - `time_in_call_secs` (integer, optional) ### ConversationHistoryTranscriptToolCallCommonModelOutputToolDetails - `type`: `api_integration_webhook` - `credential_id` (string, required, default: ) - `integration_connection_id` (string, required, default: ) - `integration_id` (string, required, default: ) - `webhook_details` (ConversationHistoryTranscriptToolCallWebhookDetails, required) - `type`: `client` - `parameters` (string, required) - `type`: `mcp` - `approval_policy` (string, required) - `integration_type` (string, required) - `mcp_server_id` (string, required) - `mcp_server_name` (string, required) - `mcp_tool_description` (string, optional, default: ) - `mcp_tool_name` (string, optional, default: ) - `parameters` (map from string to string, optional) - `requires_approval` (boolean, optional, default: false) - `type`: `webhook` - `method` (string, required) - `url` (string, required) - `body` (string, optional) - `headers` (map from string to string, optional) - `path_params` (map from string to string, optional) - `query_params` (map from string to string, optional) ### ConversationHistoryTranscriptOtherToolsResultCommonModel - `request_id` (string, required) - `tool_name` (string, required) - `result_value` (string, required) - `is_error` (boolean, required) - `tool_has_been_called` (boolean, required) - `is_blocked` (boolean, optional, default: false) - `tool_latency_secs` (double, optional, default: 0) - `error_type` (string, optional, default: ) - `raw_error_message` (string, optional, default: ) - `dynamic_variable_updates` (list of DynamicVariableUpdateCommonModel, optional) - `type` (enum, optional) - Allowed values: `client`, `webhook`, `mcp`, `code` ### ConversationHistoryTranscriptSystemToolResultCommonModelOutput - `request_id` (string, required) - `tool_name` (string, required) - `result_value` (string, required) - `is_error` (boolean, required) - `tool_has_been_called` (boolean, required) - `type` ("system", required) - `is_blocked` (boolean, optional, default: false) - `tool_latency_secs` (double, optional, default: 0) - `error_type` (string, optional, default: ) - `raw_error_message` (string, optional, default: ) - `dynamic_variable_updates` (list of DynamicVariableUpdateCommonModel, optional) - `result` (ConversationHistoryTranscriptSystemToolResultCommonModelOutputResult, optional) ### ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModelOutput - `request_id` (string, required) - `tool_name` (string, required) - `result_value` (string, required) - `is_error` (boolean, required) - `is_blocked` (boolean, required, default: false) - `tool_has_been_called` (boolean, required) - `tool_latency_secs` (double, required, default: 0) - `error_type` (string, required, default: ) - `raw_error_message` (string, required, default: ) - `dynamic_variable_updates` (list of DynamicVariableUpdateCommonModel, required) - `type` ("api_integration_webhook", required) - `integration_id` (string, required, default: ) - `credential_id` (string, required, default: ) - `integration_connection_id` (string, required, default: ) ### ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput - `request_id` (string, required) - `tool_name` (string, required) - `result_value` (string, required) - `is_error` (boolean, required) - `tool_has_been_called` (boolean, required) - `type` ("workflow", required) - `is_blocked` (boolean, optional, default: false) - `tool_latency_secs` (double, optional, default: 0) - `error_type` (string, optional, default: ) - `raw_error_message` (string, optional, default: ) - `dynamic_variable_updates` (list of DynamicVariableUpdateCommonModel, optional) - `result` (WorkflowToolResponseModelOutput, optional) — Un modello comune per le risposte degli strumenti del workflow. ### MetricRecord - `elapsed_time` (double, required) ### RagChunkMetadata - `document_id` (string, required) - `chunk_id` (string, required) - `vector_distance` (double, required) ### LlmInputOutputTokensUsage - `input` (LlmTokensCategoryUsage, optional) - `input_cache_read` (LlmTokensCategoryUsage, optional) - `input_cache_write` (LlmTokensCategoryUsage, optional) - `output_total` (LlmTokensCategoryUsage, optional) ### LiteralJsonSchemaProperty Proprietà dello schema per tipi JSON letterali. IMPORTANTE: puoi impostare UN SOLO dei seguenti campi: description (il LLM fornisce il valore), dynamic_variable (valore da variabile), is_system_provided (il sistema fornisce il valore), constant_value (valore fisso) oppure is_omitted (il parametro viene omesso). Sono mutuamente esclusivi. - `type` (LiteralJsonSchemaPropertyType, required) - `description` (string, optional, default: ) — La descrizione della proprietà. Se impostata, l'LLM fornirà il valore in base a questa descrizione. Si esclude a vicenda con dynamic_variable, is_system_provided, constant_value e is_omitted. - `enum` (list of string, optional) — List of allowed string values for string type parameters - `is_system_provided` (boolean, optional, default: false) — Se true, il valore verrà popolato dal sistema a runtime. Utilizzato dagli strumenti Webhook di integrazione API per i template. Si esclude a vicenda con description, dynamic_variable, constant_value e is_omitted. - `dynamic_variable` (string, optional, default: ) — Il nome della variabile dinamica da usare per il valore di questa proprietà. Si esclude a vicenda con description, is_system_provided, constant_value e is_omitted. - `allowed_values` (AllowedValues, optional) — Controllo di rifiuto lato server per un valore fornito da un LLM: il runtime rifiuta qualsiasi valore esterno all'insieme consentito specificato da questo oggetto e l'insieme non viene comunicato all'LLM come enum. Supportato solo quando l'origine del valore è `description`; la combinazione con dynamic_variable, is_system_provided, constant_value o is_omitted viene rifiutata. - `constant_value` (LiteralJsonSchemaPropertyConstantValue, optional) — Un valore costante da usare per questa proprietà. È mutuamente esclusivo con description, dynamic_variable, is_system_provided e is_omitted. - `is_omitted` (boolean, optional, default: false) — Se true, questo parametro verrà completamente omesso dalla richiesta. Valido solo per i parametri facoltativi. Si esclude a vicenda con description, dynamic_variable, is_system_provided e constant_value. - `allowed_values_dynamic_variable` (string, optional, default: , deprecated) — DEPRECATO: usa invece `allowed_values`. Se impostato, l'LLM fornisce il valore, ma il runtime rifiuta qualsiasi valore non presente nell'elenco contenuto in questa variabile dinamica (deve essere un array JSON come ["ws_alpha", "ws_beta"]). Usalo per consentire all'LLM di scegliere da un insieme verificato dal server, ad esempio gli ID a cui l'utente corrente può accedere. Richiede description; è mutuamente esclusivo con dynamic_variable, is_system_provided, constant_value e is_omitted. ### BuiltInToolsOutput Strumenti di sistema che possono essere assegnati a un agente conversazionale. Il nome non è volutamente ConversationalBuiltInTools: BuiltInToolsInput e BuiltInToolsOutput fanno parte della specifica API pubblica e degli SDK generati. - `transfer_to_agent` (SystemToolConfigOutput, optional) — Lo strumento di trasferimento all'agente - `end_call` (SystemToolConfigOutput, optional) — Lo strumento di fine chiamata - `language_detection` (SystemToolConfigOutput, optional) — Lo strumento di rilevamento della lingua - `transfer_to_number` (SystemToolConfigOutput, optional) — Lo strumento di trasferimento al numero - `skip_turn` (SystemToolConfigOutput, optional) — Lo strumento per saltare il turno - `play_keypad_touch_tone` (SystemToolConfigOutput, optional) — Lo strumento di riproduzione DTMF - `voicemail_detection` (SystemToolConfigOutput, optional) — Lo strumento di rilevamento della segreteria telefonica ### KnowledgeBaseLocator - `type` (enum, required) — Il tipo di knowledge base - Allowed values: `file`, `url`, `text`, `folder` - `name` (string, required) — Il nome della knowledge base - `id` (string, required) — L'ID della knowledge base - `usage_mode` (enum, optional, default: auto) — La modalità di utilizzo della knowledge base - Allowed values: `prompt`, `auto` ### CustomLlm - `url` (string, required) — L'URL dell'endpoint compatibile con Chat Completions - `model_id` (string, optional) — L'ID del modello da utilizzare se l'URL serve più modelli - `api_key` (CustomLlmApiKey, optional) — La chiave API per l'autenticazione. Può essere un riferimento a un segreto del workspace \{'secret\_id': '...'} o un riferimento a una variabile d'ambiente \{'env\_var\_label': '...'}. - `auth_connection` (CustomLlmAuthConnection, optional) — Connessione di autenticazione del workspace facoltativa. Sono supportate solo le connessioni di autenticazione che producono un token Authorization Bearer; non sono supportate le connessioni Basic auth, mTLS, con header personalizzato e con segreto URL. - `request_headers` (map from string to CustomLlmRequestHeadersValue, optional) — Header da includere nella richiesta - `api_version` (string, optional) — La versione dell'API da usare per la richiesta - `api_type` (enum, optional, default: chat_completions) — Il tipo di API da usare (chat_completions, responses o websocket) - Allowed values: `chat_completions`, `responses`, `websocket` ### RagConfigOutput - `enabled` (boolean, optional, default: false) - `embedding_model` (enum, optional, default: e5_mistral_7b_instruct) - Allowed values: `e5_mistral_7b_instruct`, `multilingual_e5_large_instruct` - `max_vector_distance` (double, optional, default: 0.6) — Distanza vettoriale massima dei chunk recuperati. - `max_documents_length` (integer, optional, default: 50000) — Lunghezza totale massima dei chunk di documenti recuperati da RAG. - `max_retrieved_rag_chunks_count` (integer, optional, default: 20) — Numero massimo di chunk di documenti RAG da recuperare inizialmente dal vector store. Vengono poi ulteriormente filtrati in base alla distanza vettoriale e alla lunghezza totale. - `num_candidates` (integer, optional) — Numero di candidati valutati nella ricerca vettoriale ANN. Un numero maggiore offre risultati migliori, ma aumenta la latenza. Il valore minimo consigliato è 100. Se disabilitato, viene usato il valore predefinito. - `query_rewrite_prompt_override` (string, optional) — Prompt personalizzato per riscrivere le query degli utenti prima del recupero RAG. La cronologia della conversazione verrà aggiunta automaticamente alla fine. Se non impostato, verrà utilizzato il prompt predefinito. - `knowledge_base_tool_info` (KnowledgeBaseToolInfo, optional) — Quando è impostato, l'agente usa lo strumento knowledge_base anziché lo strumento legacy knowledge_base_rag. None indica che l'agente non ha aderito. ### PromptAgentApiModelOutputBackupLlmConfig Configurazione della cascata di LLM di backup. Può essere disabilitata, usare le impostazioni predefinite del sistema o specificare un ordine personalizzato. - `preference`: `default` - `preference`: `disabled` - `preference`: `override` - `order` (list of enum, required) - Allowed values: `gpt-4o-mini`, `gpt-4o`, `gpt-4`, `gpt-4-turbo`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, `gpt-5`, `gpt-5.1`, `gpt-5.2`, `gpt-5.2-chat-latest`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-6-astra`, `gpt-6-sol`, `gpt-6-luna`, `gpt-6.1-sol`, `gpt-5-mini`, `gpt-5-nano`, `gpt-3.5-turbo`, `gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-2.0-flash`, `gemini-2.0-flash-lite`, `gemini-2.5-flash-lite`, `gemini-2.5-flash`, `gemini-3-pro-preview`, `gemini-3-flash-preview`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3.1-flash-lite`, `gemini-3.5-flash`, `gemini-3.5-flash-lite`, `gemini-3.6-flash`, `gemini-3.7-flash`, `gemini-3.8-flash`, `claude-sonnet-4-5`, `claude-opus-4-7`, `claude-opus-4-8`, `claude-opus-5`, `claude-opus-5-5`, `claude-sonnet-4-6`, `claude-sonnet-5`, `claude-sonnet-5-5`, `claude-sonnet-4`, `claude-haiku-4-5`, `claude-3-7-sonnet`, `claude-3-5-sonnet`, `claude-3-5-sonnet-v1`, `claude-3-haiku`, `grok-beta`, `custom-llm`, `qwen3-4b`, `qwen3-30b-a3b`, `qwen36-35b-a3b`, `qwen35-397b-a17b`, `gpt-oss-20b`, `gpt-oss-120b`, `glm-45-air-fp8`, `glm-52`, `deepseek-v41-flash`, `gemini-2.5-flash-preview-09-2025`, `gemini-2.5-flash-lite-preview-09-2025`, `gemini-2.5-flash-preview-05-20`, `gemini-2.5-flash-preview-04-17`, `gemini-2.5-flash-lite-preview-06-17`, `gemini-2.0-flash-lite-001`, `gemini-2.0-flash-001`, `gemini-1.5-flash-002`, `gemini-1.5-flash-001`, `gemini-1.5-pro-002`, `gemini-1.5-pro-001`, `claude-sonnet-4@20250514`, `claude-sonnet-4-5@20250929`, `claude-haiku-4-5@20251001`, `claude-3-7-sonnet@20250219`, `claude-3-5-sonnet@20240620`, `claude-3-5-sonnet-v2@20241022`, `claude-3-haiku@20240307`, `gpt-5-2025-08-07`, `gpt-5.1-2025-11-13`, `gpt-5.2-2025-12-11`, `gpt-5.4-2026-03-05`, `gpt-5.4-mini-2026-03-17`, `gpt-5.4-nano-2026-03-17`, `gpt-5.5-2026-04-23`, `gpt-5-mini-2025-08-07`, `gpt-5-nano-2025-08-07`, `gpt-4.1-2025-04-14`, `gpt-4.1-mini-2025-04-14`, `gpt-4.1-nano-2025-04-14`, `gpt-4o-mini-2024-07-18`, `gpt-4o-2024-11-20`, `gpt-4o-2024-08-06`, `gpt-4o-2024-05-13`, `gpt-4-0613`, `gpt-4-0314`, `gpt-4-turbo-2024-04-09`, `gpt-3.5-turbo-0125`, `gpt-3.5-turbo-1106`, `watt-tool-8b`, `watt-tool-70b` ### PromptAgentApiModelOutputToolsItem Il tipo di strumento - `type`: `api_integration_webhook` - `api_integration_connection_id` (string, required) - `api_integration_id` (string, required) - `assignments` (list of DynamicVariableAssignment, required) — Configurazione per estrarre valori dalle risposte degli strumenti e assegnarli alle variabili dinamiche - `description` (string, required) — Descrizione di quando usare lo strumento e di cosa fa. - `dynamic_variables` (DynamicVariablesConfig, required) — Configurazione per le variabili dinamiche - `execution_mode` (enum, required, default: immediate) — Determina quando e come viene eseguito lo strumento: 'immediate' esegue subito lo strumento quando viene richiesto dall'LLM, 'post_tool_speech' attende che l'agente finisca di parlare prima di eseguirlo, 'async' esegue lo strumento in background senza bloccare: ideale per operazioni di lunga durata. - Allowed values: `immediate`, `post_tool_speech`, `async` - `interruption_mode` (enum, required, default: allow) — Controlla se l'utente può interrompere l'agente durante questa chiamata allo strumento. 'allow' (predefinito) consente all'utente di interrompere in qualsiasi momento, 'disable_during_tool' sopprime le interruzioni solo mentre lo strumento è in esecuzione, 'disable_during_tool_and_turn' sopprime le interruzioni mentre lo strumento è in esecuzione e per la risposta dell'agente successiva. - Allowed values: `allow`, `disable_during_tool`, `disable_during_tool_and_turn` - `name` (string, required) - `pre_tool_speech` (enum, required, default: auto) — Controlla se l'agente parla prima che venga chiamato questo strumento. 'auto' (predefinito) decide in base alla latenza recente dello strumento, 'force' chiede sempre all'agente di parlare, 'off' disattiva completamente questa funzione indipendentemente dalla latenza. - Allowed values: `auto`, `force`, `off` - `response_timeout_secs` (integer, required, default: 20) — Il tempo massimo in secondi di attesa per il completamento della chiamata allo strumento. Deve essere compreso tra 5 e 300 secondi inclusi. - `tool_call_sound_behavior` (enum, required, default: auto) — Determina quando deve essere riprodotto il suono della chiamata dello strumento. 'auto' viene riprodotto solo quando è presente parlato prima dello strumento, mentre 'always' viene riprodotto a ogni chiamata dello strumento. - Allowed values: `auto`, `always` - `tool_error_handling_mode` (enum, required, default: auto) — Controlla come vengono elaborati gli errori degli strumenti prima di essere condivisi con l'agente. 'auto' determina la gestione in base al tipo di strumento (riassunto per le integrazioni native, nascosto per gli altri), 'summarized' invia un riepilogo generato da un LLM, 'passthrough' invia l'errore non elaborato, 'hide' non condivide l'errore con l'agente. - Allowed values: `auto`, `summarized`, `passthrough`, `hide` - `tool_version` (string, required, default: 1.0.0) — La versione dello strumento di integrazione API - `disable_interruptions` (boolean, required, default: false, deprecated) — DEPRECATO: usa invece `interruption_mode`. Se true, l'utente non potrà interrompere l'agente mentre questo strumento è in esecuzione. - `force_pre_tool_speech` (boolean, required, default: false, deprecated) — DEPRECATO: usa invece `pre_tool_speech`. Se true, l'agente parlerà prima della chiamata allo strumento. - `api_schema_overrides` (ApiIntegrationWebhookOverrides, optional) — Override utente applicati sopra l'api_schema di base - `tool_call_sound` (enum, optional) — Tipo di suono di chiamata dello strumento predefinito da riprodurre durante l'esecuzione. Se non specificato, non verrà riprodotto alcun suono di chiamata dello strumento. - Allowed values: `typing`, `elevator1`, `elevator2`, `elevator3`, `elevator4` - `type`: `client` - `description` (string, required) — Descrizione di quando usare lo strumento e di cosa fa. - `name` (string, required) - `assignments` (list of DynamicVariableAssignment, optional) — Configurazione per estrarre valori dalle risposte degli strumenti e assegnarli alle variabili dinamiche - `dynamic_variables` (DynamicVariablesConfig, optional) — Configurazione per le variabili dinamiche - `execution_mode` (enum, optional, default: immediate) — Determina quando e come viene eseguito lo strumento: 'immediate' esegue subito lo strumento quando viene richiesto dall'LLM, 'post_tool_speech' attende che l'agente finisca di parlare prima di eseguirlo, 'async' esegue lo strumento in background senza bloccare: ideale per operazioni di lunga durata. - Allowed values: `immediate`, `post_tool_speech`, `async` - `expects_response` (boolean, optional, default: false) — Se true, la chiamata di questo strumento deve bloccare la conversazione finché il client non risponde con una risposta passata all'llm. Se false, la conversazione continuerà senza attendere la risposta del client; è utile per mostrare contenuti a un utente senza bloccare la conversazione. - `interruption_mode` (enum, optional, default: allow) — Controlla se l'utente può interrompere l'agente durante questa chiamata allo strumento. 'allow' (predefinito) consente all'utente di interrompere in qualsiasi momento, 'disable_during_tool' sopprime le interruzioni solo mentre lo strumento è in esecuzione, 'disable_during_tool_and_turn' sopprime le interruzioni mentre lo strumento è in esecuzione e per la risposta dell'agente successiva. - Allowed values: `allow`, `disable_during_tool`, `disable_during_tool_and_turn` - `parameters` (ObjectJsonSchemaPropertyOutput, optional) — Schema per tutti i parametri da passare al client - `pre_tool_speech` (enum, optional, default: auto) — Controlla se l'agente parla prima che venga chiamato questo strumento. 'auto' (predefinito) decide in base alla latenza recente dello strumento, 'force' chiede sempre all'agente di parlare, 'off' disattiva completamente questa funzione indipendentemente dalla latenza. - Allowed values: `auto`, `force`, `off` - `response_timeout_secs` (integer, optional, default: 20) — Il tempo massimo in secondi di attesa per il completamento della chiamata allo strumento. Deve essere compreso tra 1 e 120 secondi inclusi, oppure -1 per attendere indefinitamente la risposta del client (richiede expects_response). - `tool_call_sound` (enum, optional) — Tipo di suono di chiamata dello strumento predefinito da riprodurre durante l'esecuzione. Se non specificato, non verrà riprodotto alcun suono di chiamata dello strumento. - Allowed values: `typing`, `elevator1`, `elevator2`, `elevator3`, `elevator4` - `tool_call_sound_behavior` (enum, optional, default: auto) — Determina quando deve essere riprodotto il suono della chiamata dello strumento. 'auto' viene riprodotto solo quando è presente parlato prima dello strumento, mentre 'always' viene riprodotto a ogni chiamata dello strumento. - Allowed values: `auto`, `always` - `tool_error_handling_mode` (enum, optional, default: auto) — Controlla come vengono elaborati gli errori degli strumenti prima di essere condivisi con l'agente. 'auto' determina la gestione in base al tipo di strumento (riassunto per le integrazioni native, nascosto per gli altri), 'summarized' invia un riepilogo generato da un LLM, 'passthrough' invia l'errore non elaborato, 'hide' non condivide l'errore con l'agente. - Allowed values: `auto`, `summarized`, `passthrough`, `hide` - `disable_interruptions` (boolean, optional, default: false, deprecated) — DEPRECATO: usa invece `interruption_mode`. Se true, l'utente non potrà interrompere l'agente mentre questo strumento è in esecuzione. - `force_pre_tool_speech` (boolean, optional, default: false, deprecated) — DEPRECATO: usa invece `pre_tool_speech`. Se true, l'agente parlerà prima della chiamata allo strumento. - `type`: `mcp` - `value` (any, required) - `type`: `smb` - `value` (any, required) - `type`: `system` - `name` (string, required) - `params` (SystemToolConfigOutputParams, required) - `assignments` (list of DynamicVariableAssignment, optional) — Configurazione per estrarre valori dalle risposte degli strumenti e assegnarli alle variabili dinamiche - `description` (string, optional, default: ) — Descrizione di quando usare lo strumento e di cosa fa. Lascia vuoto per utilizzare la descrizione predefinita ottimizzata per il tipo di strumento specifico. - `interruption_mode` (enum, optional, default: allow) — Controlla se l'utente può interrompere l'agente durante questa chiamata allo strumento. 'allow' (predefinito) consente all'utente di interrompere in qualsiasi momento, 'disable_during_tool' sopprime le interruzioni solo mentre lo strumento è in esecuzione, 'disable_during_tool_and_turn' sopprime le interruzioni mentre lo strumento è in esecuzione e per la risposta dell'agente successiva. - Allowed values: `allow`, `disable_during_tool`, `disable_during_tool_and_turn` - `pre_tool_speech` (enum, optional, default: auto) — Controlla se l'agente parla prima che venga chiamato questo strumento. 'auto' (predefinito) decide in base alla latenza recente dello strumento, 'force' chiede sempre all'agente di parlare, 'off' disattiva completamente questa funzione indipendentemente dalla latenza. - Allowed values: `auto`, `force`, `off` - `response_timeout_secs` (integer, optional, default: 20) — Il tempo massimo in secondi di attesa per il completamento della chiamata allo strumento. - `tool_call_sound` (enum, optional) — Tipo di suono di chiamata dello strumento predefinito da riprodurre durante l'esecuzione. Se non specificato, non verrà riprodotto alcun suono di chiamata dello strumento. - Allowed values: `typing`, `elevator1`, `elevator2`, `elevator3`, `elevator4` - `tool_call_sound_behavior` (enum, optional, default: auto) — Determina quando deve essere riprodotto il suono della chiamata dello strumento. 'auto' viene riprodotto solo quando è presente parlato prima dello strumento, mentre 'always' viene riprodotto a ogni chiamata dello strumento. - Allowed values: `auto`, `always` - `tool_error_handling_mode` (enum, optional, default: auto) — Controlla come vengono elaborati gli errori degli strumenti prima di essere condivisi con l'agente. 'auto' determina la gestione in base al tipo di strumento (riassunto per le integrazioni native, nascosto per gli altri), 'summarized' invia un riepilogo generato da un LLM, 'passthrough' invia l'errore non elaborato, 'hide' non condivide l'errore con l'agente. - Allowed values: `auto`, `summarized`, `passthrough`, `hide` - `disable_interruptions` (boolean, optional, default: false, deprecated) — DEPRECATO: usa invece `interruption_mode`. Se true, l'utente non potrà interrompere l'agente mentre questo strumento è in esecuzione. - `force_pre_tool_speech` (boolean, optional, default: false, deprecated) — DEPRECATO: usa invece `pre_tool_speech`. Se true, l'agente parlerà prima della chiamata allo strumento. - `type`: `webhook` - `api_schema` (WebhookToolApiSchemaConfigOutput, required) — Lo schema per il webhook in uscita, inclusi i parametri e la specifica dell'URL - `description` (string, required) — Descrizione di quando usare lo strumento e di cosa fa. - `name` (string, required) - `assignments` (list of DynamicVariableAssignment, optional) — Configurazione per estrarre valori dalle risposte degli strumenti e assegnarli alle variabili dinamiche - `dynamic_variables` (DynamicVariablesConfig, optional) — Configurazione per le variabili dinamiche - `execution_mode` (enum, optional, default: immediate) — Determina quando e come viene eseguito lo strumento: 'immediate' esegue subito lo strumento quando viene richiesto dall'LLM, 'post_tool_speech' attende che l'agente finisca di parlare prima di eseguirlo, 'async' esegue lo strumento in background senza bloccare: ideale per operazioni di lunga durata. - Allowed values: `immediate`, `post_tool_speech`, `async` - `follow_redirects` (boolean, optional, default: false) — Indica se risolvere un redirect dall'endpoint e restituire la risposta finale. Viene seguito un solo redirect, come richiesta GET senza il body della richiesta; nessuna configurazione di questo strumento (header, autenticazione, certificato client) viene inviata alla destinazione del redirect. Sia l'endpoint sia la destinazione del redirect devono usare HTTPS. Non supportato per gli strumenti di integrazione API. - `follow_redirects_allowed_domains` (list of string, optional) — Domini a cui può puntare un reindirizzamento, ad esempio 'test.example.com'. Obbligatorio quando si seguono i reindirizzamenti; una destinazione esterna all'elenco viene rifiutata. - `interruption_mode` (enum, optional, default: allow) — Controlla se l'utente può interrompere l'agente durante questa chiamata allo strumento. 'allow' (predefinito) consente all'utente di interrompere in qualsiasi momento, 'disable_during_tool' sopprime le interruzioni solo mentre lo strumento è in esecuzione, 'disable_during_tool_and_turn' sopprime le interruzioni mentre lo strumento è in esecuzione e per la risposta dell'agente successiva. - Allowed values: `allow`, `disable_during_tool`, `disable_during_tool_and_turn` - `pre_tool_speech` (enum, optional, default: auto) — Controlla se l'agente parla prima che venga chiamato questo strumento. 'auto' (predefinito) decide in base alla latenza recente dello strumento, 'force' chiede sempre all'agente di parlare, 'off' disattiva completamente questa funzione indipendentemente dalla latenza. - Allowed values: `auto`, `force`, `off` - `response_timeout_secs` (integer, optional, default: 20) — Il tempo massimo in secondi di attesa per il completamento della chiamata allo strumento. Deve essere compreso tra 5 e 300 secondi inclusi. - `tool_call_sound` (enum, optional) — Tipo di suono di chiamata dello strumento predefinito da riprodurre durante l'esecuzione. Se non specificato, non verrà riprodotto alcun suono di chiamata dello strumento. - Allowed values: `typing`, `elevator1`, `elevator2`, `elevator3`, `elevator4` - `tool_call_sound_behavior` (enum, optional, default: auto) — Determina quando deve essere riprodotto il suono della chiamata dello strumento. 'auto' viene riprodotto solo quando è presente parlato prima dello strumento, mentre 'always' viene riprodotto a ogni chiamata dello strumento. - Allowed values: `auto`, `always` - `tool_error_handling_mode` (enum, optional, default: auto) — Controlla come vengono elaborati gli errori degli strumenti prima di essere condivisi con l'agente. 'auto' determina la gestione in base al tipo di strumento (riassunto per le integrazioni native, nascosto per gli altri), 'summarized' invia un riepilogo generato da un LLM, 'passthrough' invia l'errore non elaborato, 'hide' non condivide l'errore con l'agente. - Allowed values: `auto`, `summarized`, `passthrough`, `hide` - `disable_interruptions` (boolean, optional, default: false, deprecated) — DEPRECATO: usa invece `interruption_mode`. Se true, l'utente non potrà interrompere l'agente mentre questo strumento è in esecuzione. - `force_pre_tool_speech` (boolean, optional, default: false, deprecated) — DEPRECATO: usa invece `pre_tool_speech`. Se true, l'agente parlerà prima della chiamata allo strumento. ### ConversationHistoryTranscriptToolCallCommonModelInputToolDetails - `type`: `api_integration_webhook` - `webhook_details` (ConversationHistoryTranscriptToolCallWebhookDetails, required) - `credential_id` (string, optional, default: ) - `integration_connection_id` (string, optional, default: ) - `integration_id` (string, optional, default: ) - `type`: `client` - `parameters` (string, required) - `type`: `mcp` - `approval_policy` (string, required) - `integration_type` (string, required) - `mcp_server_id` (string, required) - `mcp_server_name` (string, required) - `mcp_tool_description` (string, optional, default: ) - `mcp_tool_name` (string, optional, default: ) - `parameters` (map from string to string, optional) - `requires_approval` (boolean, optional, default: false) - `type`: `webhook` - `method` (string, required) - `url` (string, required) - `body` (string, optional) - `headers` (map from string to string, optional) - `path_params` (map from string to string, optional) - `query_params` (map from string to string, optional) ### ConversationHistoryTranscriptSystemToolResultCommonModelInput - `request_id` (string, required) - `tool_name` (string, required) - `result_value` (string, required) - `is_error` (boolean, required) - `tool_has_been_called` (boolean, required) - `type` ("system", required) - `is_blocked` (boolean, optional, default: false) - `tool_latency_secs` (double, optional, default: 0) - `error_type` (string, optional, default: ) - `raw_error_message` (string, optional, default: ) - `dynamic_variable_updates` (list of DynamicVariableUpdateCommonModel, optional) - `result` (ConversationHistoryTranscriptSystemToolResultCommonModelInputResult, optional) ### ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModelInput - `request_id` (string, required) - `tool_name` (string, required) - `result_value` (string, required) - `is_error` (boolean, required) - `tool_has_been_called` (boolean, required) - `type` ("api_integration_webhook", required) - `is_blocked` (boolean, optional, default: false) - `tool_latency_secs` (double, optional, default: 0) - `error_type` (string, optional, default: ) - `raw_error_message` (string, optional, default: ) - `dynamic_variable_updates` (list of DynamicVariableUpdateCommonModel, optional) - `integration_id` (string, optional, default: ) - `credential_id` (string, optional, default: ) - `integration_connection_id` (string, optional, default: ) ### ConversationHistoryTranscriptWorkflowToolsResultCommonModelInput - `request_id` (string, required) - `tool_name` (string, required) - `result_value` (string, required) - `is_error` (boolean, required) - `tool_has_been_called` (boolean, required) - `type` ("workflow", required) - `is_blocked` (boolean, optional, default: false) - `tool_latency_secs` (double, optional, default: 0) - `error_type` (string, optional, default: ) - `raw_error_message` (string, optional, default: ) - `dynamic_variable_updates` (list of DynamicVariableUpdateCommonModel, optional) - `result` (WorkflowToolResponseModelInput, optional) — Un modello comune per le risposte degli strumenti del workflow. ### ConversationHistoryTranscriptToolCallWebhookDetails - `method` (string, required) - `url` (string, required) - `type` ("webhook", optional) - `headers` (map from string to string, optional) - `path_params` (map from string to string, optional) - `query_params` (map from string to string, optional) - `body` (string, optional) ### DynamicVariableUpdateCommonModel Tiene traccia dell'aggiornamento di una variabile dinamica avvenuto durante l'esecuzione del tool. - `variable_name` (string, required) - `new_value` (string, required) - `updated_at` (double, required) - `tool_name` (string, required) - `tool_request_id` (string, required) - `old_value` (string, optional) ### ConversationHistoryTranscriptSystemToolResultCommonModelOutputResult - `result_type`: `dummy` - `result_type`: `end_call_success` - `message` (string, optional) - `reason` (string, optional) - `status` ("success", optional) - `result_type`: `end_procedure_error` - `message` (string, required) - `status` (enum, required) - Allowed values: `not_found`, `invalid_id` - `procedure_id` (string, optional) - `result_type`: `end_procedure_success` - `procedure_id` (string, required) - `procedure_name` (string, required) - `message` (string, optional, default: ) - `status` ("success", optional) - `result_type`: `knowledge_base_rag_success` - `chunk_count` (integer, optional, default: 0) — Numero di blocchi pertinenti recuperati - `chunks` (list of KnowledgeBaseRagChunkModel, optional) — Chunk recuperati; popolati solo nella modalità rag-result-in-tool-result - `message` (string, optional, default: Referenced knowledge base.) — Stato leggibile per l'LLM relativo ai risultati della ricerca - `status` (enum, optional, default: success) - Allowed values: `success`, `no_documents`, `no_results` - `result_type`: `knowledge_base_success` - `chunk_count` (integer, optional, default: 0) - `message` (string, optional, default: Referenced knowledge base.) - `status` (enum, optional, default: success) - Allowed values: `success`, `no_matching_documents`, `no_results` - `result_type`: `language_detection_success` - `language` (string, optional) - `reason` (string, optional) - `status` ("success", optional) - `result_type`: `play_dtmf_error` - `error` (string, required) - `details` (string, optional) - `status` ("error", optional) - `result_type`: `play_dtmf_success` - `dtmf_tones` (string, required) - `reason` (string, optional) - `status` ("success", optional) - `result_type`: `skip_turn_success` - `reason` (string, optional) - `status` ("success", optional) - `result_type`: `start_procedure_error` - `message` (string, required) - `status` (enum, required) - Allowed values: `not_found`, `invalid_name`, `already_active` - `procedure_id` (string, optional) - `result_type`: `start_procedure_success` - `procedure_id` (string, required) - `procedure_name` (string, required) - `message` (string, optional, default: Procedure is now started. Follow its instructions from the section of your system prompt.) - `procedure_entry_workflow_node` (string, optional) - `procedure_return_workflow_node` (string, optional) - `status` ("success", optional) - `result_type`: `testing_tool_result` - `reason` (string, optional, default: Skipping tool call in test mode) - `status` ("success", optional) - `result_type`: `transfer_to_agent_error` - `error` (string, required) - `from_agent` (string, required) - `status` ("error", optional) - `result_type`: `transfer_to_agent_success` - `condition` (string, required) - `from_agent` (string, required) - `to_agent` (string, required) - `branch_info` (TransferToAgentToolResultSuccessModelOutputBranchInfo, optional) - `delay_ms` (integer, optional, default: 0) - `enable_transferred_agent_first_message` (boolean, optional, default: false) - `preserve_client_tts_overrides` (boolean, optional, default: false) - `preserve_voice_settings` (boolean, optional, default: false) - `status` ("success", optional) - `to_node` (string, optional) - `transfer_message` (string, optional) - `result_type`: `transfer_to_number_amazon_connect_success` - `client_message` (string, optional) — Messaggio pronunciato a chi chiama prima che la sessione venisse restituita ad Amazon Connect. - `note` (string, optional) — Impostato quando l'agente ha ripetuto un'opzione non valida ed è stata usata l'unica opzione configurata. - `reason` (string, optional) — Motivo per cui l'agente ha eseguito l'escalation, inviato ad Amazon Connect con l'esito Escalate. - `status` ("success", optional) - `result_type`: `transfer_to_number_error` - `error` (string, required) - `details` (string, optional) - `status` ("error", optional) - `result_type`: `transfer_to_number_exotel_success` - `transfer_number` (string, required) - `agent_message` (string, optional) - `note` (string, optional) - `reason` (string, optional) - `status` ("success", optional) - `result_type`: `transfer_to_number_sip_success` - `transfer_number` (string, required) - `note` (string, optional) - `reason` (string, optional) - `status` ("success", optional) - `result_type`: `transfer_to_number_twilio_success` - `agent_message` (string, required) - `conference_name` (string, required) - `transfer_number` (string, required) - `client_message` (string, optional) - `note` (string, optional) - `post_dial_digits` (string, optional) - `reason` (string, optional) - `status` ("success", optional) - `result_type`: `voicemail_detection_success` - `reason` (string, optional) - `status` ("success", optional) - `voicemail_message` (string, optional) ### WorkflowToolResponseModelOutput Un modello comune per le risposte degli strumenti del workflow. - `steps` (list of WorkflowToolResponseModelOutputStepsItem, optional) ### LlmTokensCategoryUsage - `tokens` (integer, optional, default: 0) - `price` (double, optional, default: 0) ### LiteralJsonSchemaPropertyType ### AllowedValues - `dynamic_variable` (string, required) — Nome di una variabile dinamica che deve risolversi in un array JSON di valori consentiti, ad esempio ["ws_alpha", "ws_beta"]. Le variabili di sistema funzionano solo se si risolvono in un elenco. ### LiteralJsonSchemaPropertyConstantValue Un valore costante da usare per questa proprietà. È mutuamente esclusivo con description, dynamic_variable, is_system_provided e is_omitted. ### SystemToolConfigOutput Uno strumento di sistema è uno strumento usato per chiamare un metodo di sistema sul server - `name` (string, required) - `params` (SystemToolConfigOutputParams, required) - `type` ("system", optional) — Il tipo di strumento - `description` (string, optional, default: ) — Descrizione di quando usare lo strumento e di cosa fa. Lascia vuoto per utilizzare la descrizione predefinita ottimizzata per il tipo di strumento specifico. - `response_timeout_secs` (integer, optional, default: 20) — Il tempo massimo in secondi di attesa per il completamento della chiamata allo strumento. - `interruption_mode` (enum, optional, default: allow) — Controlla se l'utente può interrompere l'agente durante questa chiamata allo strumento. 'allow' (predefinito) consente all'utente di interrompere in qualsiasi momento, 'disable_during_tool' sopprime le interruzioni solo mentre lo strumento è in esecuzione, 'disable_during_tool_and_turn' sopprime le interruzioni mentre lo strumento è in esecuzione e per la risposta dell'agente successiva. - Allowed values: `allow`, `disable_during_tool`, `disable_during_tool_and_turn` - `pre_tool_speech` (enum, optional, default: auto) — Controlla se l'agente parla prima che venga chiamato questo strumento. 'auto' (predefinito) decide in base alla latenza recente dello strumento, 'force' chiede sempre all'agente di parlare, 'off' disattiva completamente questa funzione indipendentemente dalla latenza. - Allowed values: `auto`, `force`, `off` - `assignments` (list of DynamicVariableAssignment, optional) — Configurazione per estrarre valori dalle risposte degli strumenti e assegnarli alle variabili dinamiche - `tool_call_sound` (enum, optional) — Tipo di suono di chiamata dello strumento predefinito da riprodurre durante l'esecuzione. Se non specificato, non verrà riprodotto alcun suono di chiamata dello strumento. - Allowed values: `typing`, `elevator1`, `elevator2`, `elevator3`, `elevator4` - `tool_call_sound_behavior` (enum, optional, default: auto) — Determina quando deve essere riprodotto il suono della chiamata dello strumento. 'auto' viene riprodotto solo quando è presente parlato prima dello strumento, mentre 'always' viene riprodotto a ogni chiamata dello strumento. - Allowed values: `auto`, `always` - `tool_error_handling_mode` (enum, optional, default: auto) — Controlla come vengono elaborati gli errori degli strumenti prima di essere condivisi con l'agente. 'auto' determina la gestione in base al tipo di strumento (riassunto per le integrazioni native, nascosto per gli altri), 'summarized' invia un riepilogo generato da un LLM, 'passthrough' invia l'errore non elaborato, 'hide' non condivide l'errore con l'agente. - Allowed values: `auto`, `summarized`, `passthrough`, `hide` - `disable_interruptions` (boolean, optional, default: false, deprecated) — DEPRECATO: usa invece `interruption_mode`. Se true, l'utente non potrà interrompere l'agente mentre questo strumento è in esecuzione. - `force_pre_tool_speech` (boolean, optional, default: false, deprecated) — DEPRECATO: usa invece `pre_tool_speech`. Se true, l'agente parlerà prima della chiamata allo strumento. ### CustomLlmApiKey La chiave API per l'autenticazione. Può essere un riferimento a un segreto del workspace \{'secret\_id': '...'} o un riferimento a una variabile d'ambiente \{'env\_var\_label': '...'}. ### CustomLlmAuthConnection Connessione di autenticazione del workspace facoltativa. Sono supportate solo le connessioni di autenticazione che producono un token Authorization Bearer; non sono supportate le connessioni Basic auth, mTLS, con header personalizzato e con segreto URL. ### CustomLlmRequestHeadersValue ### KnowledgeBaseToolInfo - `enabled_strategies` (list of enum, optional) — Strategie di ricerca esposte al modello. Non può essere vuoto. - Allowed values: `cat`, `keyword`, `semantic`, `ls` ### DynamicVariableAssignment Configurazione per estrarre valori dalle risposte degli strumenti e assegnarli alle variabili dinamiche. - `dynamic_variable` (string, required) — Il nome della variabile dinamica a cui assegnare il valore estratto - `value_path` (string, required) — Path in notazione puntata per estrarre il valore dalla sorgente (ad esempio, 'user.name' o 'data.0.id') - `source` ("response", optional) — La sorgente da cui estrarre il valore. Al momento è supportato solo 'response'. - `sanitize` (boolean, optional, default: false) — Se true, il valore di questa assegnazione verrà rimosso dalla risposta dello strumento prima dell'invio all'LLM e alla trascrizione, ma verrà comunque elaborato per l'assegnazione delle variabili. - `preserve_native_type` (boolean, optional, default: false) — Se true, i valori non scalari, come elenchi e oggetti, estratti dalla risposta dello strumento vengono archiviati nel loro tipo nativo anziché essere convertiti in stringhe JSON. Abilita questa opzione per usare direttamente gli array estratti come variabili dinamiche di elenco. ### DynamicVariablesConfig - `dynamic_variable_placeholders` (map from string to any, optional) — Un dizionario di segnaposto di variabili dinamiche e dei relativi valori. ### ApiIntegrationWebhookOverrides - `schema_overrides` (map from string to ApiIntegrationWebhookOverridesSchemaOverridesValue, optional) - `response_filter_mode` (enum, optional, default: all) — Controlla come vengono filtrate le risposte degli strumenti prima di essere visibili all'agente. - Allowed values: `all`, `allow`, `hide_all` - `response_filters` (list of string, optional) - `request_headers` (map from string to ApiIntegrationWebhookOverridesRequestHeadersValue, optional) ### ObjectJsonSchemaPropertyOutput - `description` (string, optional, default: ) - `dynamic_variable` (string, optional, default: ) — Quando è impostato, l'intero parametro viene popolato da questa variabile dinamica in fase di runtime. Si esclude a vicenda con description (valore fornito dall'LLM), constant_value e is_omitted. - `constant_value` (map from string to any, optional) — Quando è impostato, l'intero oggetto usa questo valore JSON costante in fase di runtime. Si esclude a vicenda con description (oggetto fornito dall'LLM), dynamic_variable e is_omitted. - `is_omitted` (boolean, optional, default: false) — Se true, questo parametro verrà completamente omesso dalla richiesta. Valido solo per i parametri facoltativi. Si esclude a vicenda con description, dynamic_variable e constant_value. - `type` ("object", optional) - `required` (list of string, optional) - `properties` (map from string to ObjectJsonSchemaPropertyOutputPropertiesValue, optional) - `required_constraints` (RequiredConstraints, optional) — Wrapper per i vincoli di composizione anyOf/allOf limitati ai campi obbligatori. ### SystemToolConfigOutputParams - `system_tool_type`: `end_call` - `system_tool_type`: `end_procedure` - `procedures` (map from string to EndProcedureToolConfigProceduresValue, optional) - `system_tool_type`: `knowledge_base` - `enabled_strategies` (list of enum, optional) - Allowed values: `cat`, `keyword`, `semantic`, `ls` - `system_tool_type`: `knowledge_base_rag` - `system_tool_type`: `language_detection` - `only_at_conversation_start` (boolean, optional, default: false) — Se non avviene alcun cambio di lingua nei primi 2 turni dell'utente, i tentativi successivi non riusciranno e la conversazione rimarrà nella lingua corrente. Se la lingua cambia durante questi turni, i cambi successivi restano disponibili. Abilita questa opzione per ridurre la possibilità di cambi errati. - `system_tool_type`: `play_keypad_touch_tone` - `suppress_turn_after_dtmf` (boolean, optional, default: false) — Se true, l'agente non genererà altro parlato dopo aver riprodotto i toni DTMF. Ciò impedisce che il parlato dell'agente interferisca con i sistemi IVR. - `use_out_of_band_dtmf` (boolean, optional, default: true) — Invia i toni DTMF come eventi RTP out-of-band (RFC 4733) anziché come audio in-band. Efficace solo per i numeri importati da trunk SIP. - `system_tool_type`: `skip_turn` - `wait_timeout_secs` (double, optional, default: -1) — Secondi di attesa dopo skip_turn prima che l'agente generi un messaggio di verifica contestuale. Il timer "End conversation after silence" viene sospeso durante l'attesa. -1 disabilita l'attesa: dopo skip_turn l'agente resta in silenzio finché il chiamante non parla e il timer continua a scorrere. Si applica solo alle conversazioni vocali. - `system_tool_type`: `start_procedure` - `procedures` (map from string to StartProcedureToolConfigProceduresValue, optional) - `system_tool_type`: `transfer_to_agent` - `transfers` (list of AgentTransferOutput, required) - `system_tool_type`: `transfer_to_number` - `transfers` (list of PhoneNumberTransfer, required) - `enable_client_message` (boolean, optional, default: true) — Indica se riprodurre un messaggio al cliente mentre attende il trasferimento. Per la retrocompatibilità, il valore predefinito è true. - `system_tool_type`: `voicemail_detection` - `voicemail_message` (string, optional) — Messaggio facoltativo da lasciare nella segreteria telefonica quando viene rilevata. Se non viene fornito, la chiamata termina immediatamente al rilevamento della segreteria. Supporta variabili dinamiche, ad esempio \{\{system\_\_time}}, \{\{system\_\_call\_duration\_secs}}, \{\{custom\_variable}}. ### WebhookToolApiSchemaConfigOutput - `url` (string, required) — L'URL a cui verrà inviato il webhook. Può includere parametri path, ad es. [https://example.com/agents/\{agent\_id}](https://example.com/agents/\{agent_id}) - `request_headers` (map from string to WebhookToolApiSchemaConfigOutputRequestHeadersValue, optional) — Header da includere nella richiesta - `method` (enum, optional, default: GET) — Il metodo HTTP da usare per il webhook - Allowed values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE` - `path_params_schema` (map from string to LiteralJsonSchemaProperty, optional) — Schema per eventuali parametri del path. Le chiavi devono corrispondere ai segnaposto nell'URL. - `query_params_schema` (QueryParamsJsonSchemaOutput, optional) — Schema per eventuali query params. Verranno aggiunti alla fine dell'URL come query params. Nota: le proprietà in un query param devono essere tutte di tipi letterali. - `request_body_schema` (ObjectJsonSchemaPropertyOutput, optional) — Schema per eventuali parametri del body. Utilizzato per le richieste POST/PATCH/PUT. Lo schema deve essere un oggetto che verrà inviato come body JSON. - `response_body_schema` (ObjectJsonSchemaPropertyOutput, optional) — Schema che descrive la struttura prevista del body della risposta. Solo a scopo di documentazione; non viene esposto al LLM. - `response_filter` (ResponseFilter, optional) — Filtro facoltativo di allow-list applicato alla risposta prima che l'LLM la elabori, affinché le risposte di grandi dimensioni non sovraccarichino il contesto. Per impostazione predefinita viene usata la risposta completa. - `content_type` (enum, optional, default: application/json) — Tipo di contenuto per il body della richiesta. Si applica solo alle richieste POST/PUT/PATCH. - Allowed values: `application/json`, `application/x-www-form-urlencoded` - `auth_resolved_params` (list of string, optional) — Segnaposto URL risolti dalla connessione di autenticazione (ad esempio, segreti inseriti tramite UrlSecretAuthConnection) anziché da path_params_schema. - `auth_connection` (WebhookToolApiSchemaConfigOutputAuthConnection, optional) — Connessione di autenticazione facoltativa da usare per l'autenticazione con questo webhook ### ConversationHistoryTranscriptSystemToolResultCommonModelInputResult - `result_type`: `dummy` - `result_type`: `end_call_success` - `message` (string, optional) - `reason` (string, optional) - `status` ("success", optional) - `result_type`: `end_procedure_error` - `message` (string, required) - `status` (enum, required) - Allowed values: `not_found`, `invalid_id` - `procedure_id` (string, optional) - `result_type`: `end_procedure_success` - `procedure_id` (string, required) - `procedure_name` (string, required) - `message` (string, optional, default: ) - `status` ("success", optional) - `result_type`: `knowledge_base_rag_success` - `chunk_count` (integer, optional, default: 0) — Numero di blocchi pertinenti recuperati - `chunks` (list of KnowledgeBaseRagChunkModel, optional) — Chunk recuperati; popolati solo nella modalità rag-result-in-tool-result - `message` (string, optional, default: Referenced knowledge base.) — Stato leggibile per l'LLM relativo ai risultati della ricerca - `status` (enum, optional, default: success) - Allowed values: `success`, `no_documents`, `no_results` - `result_type`: `knowledge_base_success` - `chunk_count` (integer, optional, default: 0) - `message` (string, optional, default: Referenced knowledge base.) - `status` (enum, optional, default: success) - Allowed values: `success`, `no_matching_documents`, `no_results` - `result_type`: `language_detection_success` - `language` (string, optional) - `reason` (string, optional) - `status` ("success", optional) - `result_type`: `play_dtmf_error` - `error` (string, required) - `details` (string, optional) - `status` ("error", optional) - `result_type`: `play_dtmf_success` - `dtmf_tones` (string, required) - `reason` (string, optional) - `status` ("success", optional) - `result_type`: `skip_turn_success` - `reason` (string, optional) - `status` ("success", optional) - `result_type`: `start_procedure_error` - `message` (string, required) - `status` (enum, required) - Allowed values: `not_found`, `invalid_name`, `already_active` - `procedure_id` (string, optional) - `result_type`: `start_procedure_success` - `procedure_id` (string, required) - `procedure_name` (string, required) - `message` (string, optional, default: Procedure is now started. Follow its instructions from the section of your system prompt.) - `procedure_entry_workflow_node` (string, optional) - `procedure_return_workflow_node` (string, optional) - `status` ("success", optional) - `result_type`: `testing_tool_result` - `reason` (string, optional, default: Skipping tool call in test mode) - `status` ("success", optional) - `result_type`: `transfer_to_agent_error` - `error` (string, required) - `from_agent` (string, required) - `status` ("error", optional) - `result_type`: `transfer_to_agent_success` - `condition` (string, required) - `from_agent` (string, required) - `to_agent` (string, required) - `branch_info` (TransferToAgentToolResultSuccessModelInputBranchInfo, optional) - `delay_ms` (integer, optional, default: 0) - `enable_transferred_agent_first_message` (boolean, optional, default: false) - `preserve_client_tts_overrides` (boolean, optional, default: false) - `preserve_voice_settings` (boolean, optional, default: false) - `status` ("success", optional) - `to_node` (string, optional) - `transfer_message` (string, optional) - `result_type`: `transfer_to_number_amazon_connect_success` - `client_message` (string, optional) — Messaggio pronunciato a chi chiama prima che la sessione venisse restituita ad Amazon Connect. - `note` (string, optional) — Impostato quando l'agente ha ripetuto un'opzione non valida ed è stata usata l'unica opzione configurata. - `reason` (string, optional) — Motivo per cui l'agente ha eseguito l'escalation, inviato ad Amazon Connect con l'esito Escalate. - `status` ("success", optional) - `result_type`: `transfer_to_number_error` - `error` (string, required) - `details` (string, optional) - `status` ("error", optional) - `result_type`: `transfer_to_number_exotel_success` - `transfer_number` (string, required) - `agent_message` (string, optional) - `note` (string, optional) - `reason` (string, optional) - `status` ("success", optional) - `result_type`: `transfer_to_number_sip_success` - `transfer_number` (string, required) - `note` (string, optional) - `reason` (string, optional) - `status` ("success", optional) - `result_type`: `transfer_to_number_twilio_success` - `agent_message` (string, required) - `conference_name` (string, required) - `transfer_number` (string, required) - `client_message` (string, optional) - `note` (string, optional) - `post_dial_digits` (string, optional) - `reason` (string, optional) - `status` ("success", optional) - `result_type`: `voicemail_detection_success` - `reason` (string, optional) - `status` ("success", optional) - `voicemail_message` (string, optional) ### WorkflowToolResponseModelInput Un modello comune per le risposte degli strumenti del workflow. - `steps` (list of WorkflowToolResponseModelInputStepsItem, optional) ### KnowledgeBaseRagChunkModel - `chunk_id` (string, required) - `document_id` (string, required) - `content` (string, required) ### TransferToAgentToolResultSuccessModelOutputBranchInfo - `branch_reason`: `configured` - `branch_id` (string, required) - `branch_reason`: `defaulting_to_main` - `branch_id` (string, required) - `branch_reason`: `traffic_split` - `branch_id` (string, required) - `traffic_percentage` (double, required) ### WorkflowToolResponseModelOutputStepsItem - `type`: `edge` - `edge_id` (string, required) - `step_latency_secs` (double, required) - `target_node_id` (string, required) - `type`: `max_iterations_exceeded` - `max_iterations` (integer, required) - `step_latency_secs` (double, required) - `type`: `nested_tools` - `is_successful` (boolean, required) - `node_id` (string, required) - `requests` (list of ConversationHistoryTranscriptToolCallCommonModelOutput, required) - `results` (list of WorkflowToolNestedToolsStepModelOutputResultsItem, required) - `step_latency_secs` (double, required) ### ConvAiSecretLocator Usato per fare riferimento a un segreto dall'archivio dei segreti dell'agente. - `secret_id` (string, required) ### ConvAiEnvVarLocator Usato per fare riferimento a una variabile d'ambiente tramite etichetta. - `env_var_label` (string, required) ### AuthConnectionLocator Usato per fare riferimento a una connessione di autenticazione dall'archivio delle connessioni di autenticazione del workspace. - `auth_connection_id` (string, required) ### EnvironmentAuthConnectionLocator Fa riferimento tramite etichetta a una variabile di ambiente di tipo 'auth_connection'. In fase di runtime, viene risolta nella connessione di autenticazione dell'ambiente corrente, con fallback all'ambiente predefinito. - `env_var_label` (string, required) ### ConvAiDynamicVariable Usato per fare riferimento a una variabile dinamica. - `variable_name` (string, required) ### ApiIntegrationWebhookOverridesSchemaOverridesValue - `source`: `constant` - `constant_value` (ConstantSchemaOverrideConstantValue, optional) — Il valore costante da usare - `source`: `dynamic_variable` - `dynamic_variable` (string, required) — Il nome della variabile dinamica da usare - `source`: `llm` - `prompt` (string, optional) — Sostituzione del prompt per l'LLM. Se non fornita, viene utilizzata la descrizione originale dello schema. - `source`: `omit` ### ApiIntegrationWebhookOverridesRequestHeadersValue ### ObjectJsonSchemaPropertyOutputPropertiesValue ### RequiredConstraints Wrapper per i vincoli di composizione anyOf/allOf limitati ai campi obbligatori. - `any_of` (list of RequiredConstraint, optional) - `all_of` (list of RequiredConstraint, optional) ### EndProcedureToolConfigProceduresValue ### StartProcedureToolConfigProceduresValue ### AgentTransferOutput - `condition` (string, required) - `agent_id` (string, optional) - `branch_id` (string, optional) - `node_id` (string, optional) - `delay_ms` (integer, optional, default: 0) - `transfer_message` (string, optional) - `enable_transferred_agent_first_message` (boolean, optional, default: false) - `is_workflow_node_transfer` (boolean, optional, default: false) - `preserve_client_tts_overrides` (boolean, optional, default: false) — Definisce se gli override del client TTS debbano essere trasferiti all'agente di destinazione. - `preserve_voice_settings` (boolean, optional, default: false) — Definisce se la voce di base, il modello TTS e le impostazioni vocali debbano essere trasferiti all'agente di destinazione. ### PhoneNumberTransfer - `transfer_destination` (PhoneNumberTransferTransferDestination, required) - `condition` (string, required) - `custom_sip_headers` (list of PhoneNumberTransferCustomSipHeadersItem, optional) — Header SIP personalizzati da includere durante il trasferimento della chiamata. Ogni header può essere un valore statico o un riferimento a variabile dinamica. - `transfer_type` (enum, optional, default: conference) - Allowed values: `blind`, `conference`, `sip_refer` - `sip_refer_play_dialtone` (boolean, optional, default: true) — Se True, viene riprodotto un tono di chiamata sulla tratta di chiamata originale durante il completamento di un trasferimento SIP REFER. Il tono viene trasmesso tramite RTP al peer SIP che esegue il REFER, quindi disabilita questa opzione se il sistema ricevente (ad esempio un SBC o un contact center) non deve sentirlo. Se disabilitata, il chiamante sente silenzio fino al completamento del trasferimento. Solo per trasferimenti SIP REFER. - `uui` (UuiTransferConfig, optional) — Informazioni User-to-User (RFC 7433) da allegare ai trasferimenti SIP REFER. Trasporta il contesto della chiamata, come identificatori CRM o il motivo dell'escalation, oltre il confine del trasferimento. - `post_dial_digits` (PhoneNumberTransferPostDialDigits, optional) — Cifre DTMF da inviare dopo la connessione della chiamata (ad esempio, 'ww1234' per l'interno). Possono essere un valore statico o un riferimento a una variabile dinamica. Usa 'w' per una pausa di 0,5 s. Supportato solo per i trasferimenti Twilio. - `phone_number` (string, optional, deprecated) ### WebhookToolApiSchemaConfigOutputRequestHeadersValue ### QueryParamsJsonSchemaOutput - `properties` (map from string to LiteralJsonSchemaProperty, required) - `required` (list of string, optional) ### ResponseFilter Configurazione per filtrare le risposte degli strumenti prima che siano visibili all'agente. - `mode` (enum, optional, default: all) — Controlla come vengono filtrate le risposte degli strumenti. 'all' restituisce l'intera risposta, 'allow' restituisce solo i path specificati, 'hide_all' nasconde l'intera risposta. - Allowed values: `all`, `allow`, `hide_all` - `filters` (list of string, optional) — Path in notazione puntata da includere quando mode è 'allow' (ad esempio, ['ticket.id', 'ticket.status']). - `content_type` ("application/json", optional) — Tipo di contenuto per il filtro delle risposte. Vengono filtrate solo le risposte 'application/json'. ### WebhookToolApiSchemaConfigOutputAuthConnection Connessione di autenticazione facoltativa da usare per l'autenticazione con questo webhook ### TransferToAgentToolResultSuccessModelInputBranchInfo - `branch_reason`: `configured` - `branch_id` (string, required) - `branch_reason`: `defaulting_to_main` - `branch_id` (string, required) - `branch_reason`: `traffic_split` - `branch_id` (string, required) - `traffic_percentage` (double, required) ### WorkflowToolResponseModelInputStepsItem - `type`: `edge` - `edge_id` (string, required) - `step_latency_secs` (double, required) - `target_node_id` (string, required) - `type`: `max_iterations_exceeded` - `max_iterations` (integer, required) - `step_latency_secs` (double, required) - `type`: `nested_tools` - `is_successful` (boolean, required) - `node_id` (string, required) - `requests` (list of ConversationHistoryTranscriptToolCallCommonModelInput, required) - `results` (list of WorkflowToolNestedToolsStepModelInputResultsItem, required) - `step_latency_secs` (double, required) ### WorkflowToolNestedToolsStepModelOutputResultsItem ### ConstantSchemaOverrideConstantValue Il valore costante da usare ### ArrayJsonSchemaPropertyOutput - `description` (string, optional, default: ) - `dynamic_variable` (string, optional, default: ) — Quando è impostato, l'intero parametro viene popolato da questa variabile dinamica in fase di runtime. Si esclude a vicenda con description (valore fornito dall'LLM), constant_value e is_omitted. - `constant_value` (list of any, optional) — Quando è impostato, l'intero array usa questo valore costante in fase di runtime. Si esclude a vicenda con description (array fornito dall'LLM), dynamic_variable e is_omitted. - `is_omitted` (boolean, optional, default: false) — Se true, questo parametro verrà completamente omesso dalla richiesta. Valido solo per i parametri facoltativi. Si esclude a vicenda con description, dynamic_variable e constant_value. - `type` ("array", optional) - `items` (ArrayJsonSchemaPropertyOutputItems, optional) — Schema per gli elementi dell'array. ### RequiredConstraint Un insieme di campi che devono essere tutti presenti per soddisfare questo vincolo. - `required` (list of string, required) ### ProcedureVersionRef - `procedure_id` (string, required) — ID della procedura - `version_id` (string, required) — ID della versione della procedura. ### ProcedureDraftRef - `procedure_id` (string, required) — ID della procedura - `version_id` (any, optional) ### PhoneNumberTransferTransferDestination - `type`: `phone` - `phone_number` (string, required) - `type`: `phone_dynamic_variable` - `phone_number` (string, required) - `type`: `sip_uri` - `sip_uri` (string, required) - `type`: `sip_uri_dynamic_variable` - `sip_uri` (string, required) ### PhoneNumberTransferCustomSipHeadersItem - `type`: `dynamic` - `key` (string, required) — Il nome dell'header SIP (ad es. 'X-Customer-ID') - `value` (string, required) — Il nome della variabile dinamica da risolvere - `type`: `static` - `key` (string, required) — Il nome dell'header SIP (ad es. 'X-Customer-ID') - `value` (string, required) — Il valore dell'header ### UuiTransferConfig Contenitore User-to-User Information per trasferimenti SIP REFER (RFC 7433). I payload in uscita sono codificati in esadecimale (l'unica codifica definita da RFC 7433). L'asse del discriminatore di protocollo consente di esprimere tramite configurazione i formati per piattaforma (Talkdesk, Genesys, ...) anziché mediante flag di trasferimento distribuiti. È possibile aggiungere qui ulteriori assi (codifica ASCII, nome dell'header, parametri di scopo/contenuto) senza modificare il modello di trasferimento. - `data` (string, required) — Payload UUI da inviare nei trasferimenti SIP REFER. Supporta variabili dinamiche inline ed è codificato in esadecimale al momento del trasferimento. - `protocol_discriminator` (string, optional) — Discriminatore di protocollo facoltativo di un ottetto, composto da due cifre esadecimali, ad esempio '00'. È richiesto da piattaforme come Genesys Cloud, che altrimenti rimuovono il primo ottetto del payload. Lascialo non impostato per piattaforme come Talkdesk, che prevedono un payload esadecimale senza prefisso. - `protocol_discriminator_mode` (enum, optional, default: prefix) — Come allegare protocol\_discriminator. 'prefix' antepone l'ottetto al payload esadecimale (User-to-User=XX\;encoding=hex). 'pd\_parameter' lo invia come parametro separato (User-to-User=\;pd=XX;encoding=hex). Ignorato quando protocol\_discriminator non è impostato. - Allowed values: `prefix`, `pd_parameter` ### PhoneNumberTransferPostDialDigits - `type`: `dynamic` - `value` (string, required) — Il nome della variabile dinamica da risolvere - `type`: `static` - `value` (string, required) — Cifre DTMF da inviare dopo la connessione della chiamata (ad esempio, 'ww1234' per l'interno) ### WorkflowToolNestedToolsStepModelInputResultsItem ### ArrayJsonSchemaPropertyOutputItems Schema per gli elementi dell'array. ## Examples **Request** ```json { "simulation_specification": { "simulated_user_config": { "first_message": "Hello, how can I help you today?", "language": "en", "disable_first_message_interruptions": false } } } ``` **Response** ```json { "simulated_conversation": [ { "role": "user", "time_in_call_secs": 1, "agent_metadata": { "agent_id": "agent_id" }, "message": "message", "multivoice_message": { "parts": [ { "text": "text", "voice_label": null, "time_in_call_secs": null } ] }, "tool_calls": [ { "request_id": "request_id", "tool_name": "tool_name", "params_as_json": "params_as_json", "tool_has_been_called": true } ], "tool_results": [ { "is_error": true, "request_id": "request_id", "result_value": "result_value", "tool_has_been_called": true, "tool_name": "tool_name" } ], "feedback": { "score": "like", "time_in_call_secs": 1 }, "llm_override": "llm_override", "producing_llm": "producing_llm", "rag_retrieval_info": { "chunks": [ { "document_id": "document_id", "chunk_id": "chunk_id", "vector_distance": 1.1 } ], "embedding_model": "e5_mistral_7b_instruct", "retrieval_query": "retrieval_query", "rag_latency_secs": 1.1 }, "interrupted": true, "ignored_as_backchannel": true, "platform_event": "user_turn_timeout", "original_message": "original_message", "reasoning": [ {} ], "source_medium": "audio", "source_event_id": 1, "used_static_kb_document_ids": [ "used_static_kb_document_ids" ], "user_identifier": "user_identifier", "id": "id", "triggered_guardrails": [ { "guardrail_type": "custom" } ], "file_input": { "file_id": "file_id", "original_filename": "original_filename", "mime_type": "mime_type", "file_url": "file_url" }, "file_inputs": [ { "file_id": "file_id", "original_filename": "original_filename", "mime_type": "mime_type", "file_url": "file_url" } ], "contextual_update_info": { "context_id": "context_id" }, "reasoned": true } ], "analysis": { "call_successful": "success", "transcript_summary": "transcript_summary", "evaluation_criteria_results": { "key": { "criteria_id": "criteria_id", "result": "success", "rationale": "rationale" } }, "data_collection_results": { "key": { "data_collection_id": "data_collection_id", "rationale": "rationale", "json_schema": { "type": "string", "description": "A user-provided message" } } }, "evaluation_criteria_results_list": [ { "criteria_id": "criteria_id", "result": "success", "rationale": "rationale" } ], "data_collection_results_list": [ { "data_collection_id": "data_collection_id", "rationale": "rationale", "json_schema": { "type": "string", "description": "A user-provided message" } } ], "call_success_score": 1.1, "call_summary_title": "call_summary_title", "scoped": [ { "scope": "conversation", "source_agent_id": "source_agent_id", "successful": "success" } ] } } ``` **SDK Code** ```python import requests url = "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation" payload = { "simulation_specification": { "simulated_user_config": { "first_message": "Hello, how can I help you today?", "language": "en", "disable_first_message_interruptions": False } } } headers = {"Content-Type": "application/json"} response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation'; const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"simulation_specification":{"simulated_user_config":{"first_message":"Hello, how can I help you today?","language":"en","disable_first_message_interruptions":false}}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation" payload := strings.NewReader("{\n \"simulation_specification\": {\n \"simulated_user_config\": {\n \"first_message\": \"Hello, how can I help you today?\",\n \"language\": \"en\",\n \"disable_first_message_interruptions\": false\n }\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Content-Type"] = 'application/json' request.body = "{\n \"simulation_specification\": {\n \"simulated_user_config\": {\n \"first_message\": \"Hello, how can I help you today?\",\n \"language\": \"en\",\n \"disable_first_message_interruptions\": false\n }\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation") .header("Content-Type", "application/json") .body("{\n \"simulation_specification\": {\n \"simulated_user_config\": {\n \"first_message\": \"Hello, how can I help you today?\",\n \"language\": \"en\",\n \"disable_first_message_interruptions\": false\n }\n }\n}") .asString(); ``` ```php request('POST', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation', [ 'body' => '{ "simulation_specification": { "simulated_user_config": { "first_message": "Hello, how can I help you today?", "language": "en", "disable_first_message_interruptions": false } } }', 'headers' => [ 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation"); var request = new RestRequest(Method.POST); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"simulation_specification\": {\n \"simulated_user_config\": {\n \"first_message\": \"Hello, how can I help you today?\",\n \"language\": \"en\",\n \"disable_first_message_interruptions\": false\n }\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Content-Type": "application/json"] let parameters = ["simulation_specification": ["simulated_user_config": [ "first_message": "Hello, how can I help you today?", "language": "en", "disable_first_message_interruptions": false ]]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```