Crear un agente

Agentes y modelos

Un agente es todo lo que oye quien llama: su idioma, su voz, el modelo que lo hace funcionar, su flujo de llamada y lo que pasa cuando termina la llamada.

Crear o duplicar

POST/v1/agents crea un agente desde cero: basta con un nombre, un género y un idioma. Para una variante de un agente que ya funciona (otro club, otro idioma, una versión de prueba), mejor duplícalo: la copia conserva el flujo de llamada, los prompts, los ajustes y el webhook asignado.

Terminal

curl -X POST "https://api.callshift.ai/v1/agents/$AGENT_ID/duplicate" \
  -H "Authorization: Bearer $CALLSHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
# { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }

curl -X PATCH "https://api.callshift.ai/v1/agents/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer $CALLSHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Alice (Spanish)", "language": "es" }'

Ajustes

Campo	Valores	Por defecto
`name`	De 1 a 50 caracteres	obligatorio
`gender`	`FEMALE`, `MALE`	obligatorio
`language`	`fr`, `en`, `nl`, `pt`, `es`	obligatorio
`provider`, `model`	Consulta Elegir un modelo	`google`, `gemini-live-3.1-flash`
`voiceId`	Una voz de la familia del modelo, tal como aparece en el selector de voces del panel. Solo escritura: `GET` no la devuelve.	La voz por defecto de la familia
`temperature`	De 0 a 2
`maxTokens`	De 1 a 10000
`silenceTimeoutSeconds`	De 5 a 120: el agente cuelga tras este tiempo de silencio del interlocutor	25
`maxDurationSeconds`	De 60 a 3600: al alcanzar ese límite, la llamada termina con `max-duration-exceeded`	420
`minEndpointingDelay`	De 0,3 a 2,5 segundos que el agente espera después de que el interlocutor deje de hablar. Solo modelos pipeline.	Valor por defecto de la plataforma
`backgroundSound`	`office_ambience`, `city_ambience`, `forest_ambience`, `crowded_room`, `keyboard_typing`, `keyboard_typing2`, `hold_music`, `gym_ambience` o `null`	Ninguno
`backgroundSoundVolume`	De 0 a 1	0,2
`summaryPrompt`, `evaluationPrompt`, `informationToCollect`	Consulta Análisis de llamadas
`diagram`	Consulta Flujo de llamadas
`entityId`, `entityExternalId`	Consulta Entidades	Compartido

Elegir un modelo

Un agente puede funcionar con dos familias de modelos.

Familia	Modelos (proveedor)	Cuándo elegirla
Speech-to-speech (tiempo real)	`gemini-3.8-live`, `gemini-live-3.1-flash` (`google`) · `gpt-realtime-2.1-mini`, `gpt-live-1` (`openai`) · `grok-voice-3.0` (`xai`)	El modelo oye y habla directamente: los turnos de palabra más naturales y las respuestas más rápidas.
Pipeline	`gpt-4o-mini`, `gpt-4o`, `gpt-4.1-mini`, `gpt-5-mini`, `gpt-5.4-mini` (`openai`)	Voz a texto, un modelo de lenguaje y después texto a voz: más variedad de voces, y más fiable con emails y números dictados. Se aplica `minEndpointingDelay`.

Nota

Envía provider y model de esta lista, y vuelve a consultar el agente con GET/v1/agents/{agentId} para confirmarlo. Para comparar las dos familias en coste y latencia, usa el simulador speech-to-speech vs pipeline.

Actualizar un agente sin riesgos

PATCH/v1/agents/{agentId} reemplaza por completo cada campo que envías y deja los demás como están. El diagram es un solo campo: consulta el agente, cambia el diagrama y vuelve a enviarlo completo.

const api = (path, init = {}) =>
  fetch(`https://api.callshift.ai${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.CALLSHIFT_API_KEY}`,
      "Content-Type": "application/json",
    },
  }).then((r) => r.json());

const agent = await api(`/v1/agents/${agentId}`);
const start = agent.diagram.nodes.find((n) => n.type === "startCall");
start.data.welcomeMessage =
  "Hello, this is Alice, the AI assistant of Club Lyon Part-Dieu. How can I help?";

await api(`/v1/agents/${agentId}`, {
  method: "PATCH",
  body: JSON.stringify({ diagram: agent.diagram }),
});

import os
import requests

API = "https://api.callshift.ai"
H = {"Authorization": f"Bearer {os.environ['CALLSHIFT_API_KEY']}"}

agent = requests.get(f"{API}/v1/agents/{agent_id}", headers=H).json()
start = next(n for n in agent["diagram"]["nodes"] if n["type"] == "startCall")
start["data"]["welcomeMessage"] = (
    "Hello, this is Alice, the AI assistant of Club Lyon Part-Dieu. How can I help?"
)

requests.patch(f"{API}/v1/agents/{agent_id}", headers=H, json={"diagram": agent["diagram"]})

Los cambios se aplican desde la siguiente llamada, y un agente no tiene historial de versiones. Duplica un agente antes de un cambio grande para conservar la versión anterior. Para una copia de staging, añade un prefijo a su nombre ([STAGING] Alice) y asigna tus números solo al agente de producción.

Eliminar un agente

DELETE/v1/agents/{agentId} elimina el agente y libera los números que tenía asignados. Sus llamadas anteriores se pueden seguir consultando.