API de Agentes de IA #

Un Agente de IA es el cerebro detrás de tu bot: sus instrucciones, personalidad, idioma, conocimientos y herramientas. Creas un Agente una vez y luego diriges el tráfico hacia él. Esta guía cubre todo lo que puedes hacer con un Agente a través de la API: crearlo, configurarlo, proporcionarle conocimientos y herramientas, revisar sus borradores y dirigirle conversaciones.

• URL base — https://api.youraiconnector.com/v1
• Autenticación — tu clave de API (consulta Autenticación)
• Errores y paginación — consulta Errores y paginación

Todos los ejemplos a continuación muestran la forma de consulta ?apiKey= en cURL y el encabezado X-API-Key en JavaScript y Python; cualquiera de los dos funciona en todos los endpoints.

Si eres nuevo en el concepto de Agentes, lee primero Agentes de IA.

Cómo se compone un Agente #

Cuatro elementos se gestionan por separado, y es útil saber cuál es cuál antes de empezar:

Un Agente nuevo no responde a nadie hasta que lo enrutas. Crear un Agente no lo coloca en un canal. Ese es el paso que la mayoría de las integraciones pasan por alto; consulta Enrutar conversaciones a un Agente al final de esta página.

El objeto Agente #

Un documento completo de Agente es grande: varios cientos de kilobytes, principalmente su lista de preguntas frecuentes, sus fuentes de conocimiento y cualquier contenido de página leído desde tu sitio web. Debido a esto, al solicitarlo, el listado devuelve una fila de resumen corta por Agente:

{
  "id": "ag7HkQ2ZpLxR3mNb",
  "name": "Listing assistant",
  "active": true,
  "language": "en",
  "goal": "Book a viewing",
  "tags": [],
  "anthropic_model": "standard",
  "ai_speed": "balanced",
  "enable_bookings": false,
  "enable_follow_ups": true,
  "faq_refs_count": 42,
  "kb_source_refs_count": 3,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

El documento completo añade todo lo demás: instructions, rules, personality, availability, follow_up_config, las listas vinculadas de preguntas frecuentes y fuentes de conocimiento, los bloques de texto generados y cualquier estado de ejecución (tag_generation, optimize_run).

Algunas respuestas también contienen substrate_campaign_id. Es un registro interno que se mantiene en cuentas antiguas; nunca necesitas actuar sobre él, y en cuentas más nuevas es null o está ausente.

Listar Agentes #

GET /agents: todos los Agentes de la cuenta, los más recientes primero.

Este endpoint no está paginado. De forma predeterminada, cada Agente se devuelve con su configuración completa, lo cual es pesado: un solo Agente puede alcanzar los 580 KB y una cuenta de 64 Agentes más de 3 MB. Pase view=summary para obtener una fila corta por Agente en su lugar, y luego lea el que desee con Obtener un Agente.

Parámetros de consulta

cURL

curl "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents?view=summary", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agents } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"view": "summary"},
)
agents = res.json()["agents"]

Respuesta (200)

{
  "success": true,
  "agents": [
    { "id": "ag7HkQ2ZpLxR3mNb", "name": "Listing assistant", "active": true }
  ]
}

Crear un Agente #

POST /agents — solo se necesita realmente name; envíe cualquier configuración que ya conozca junto con él. Un Agente nuevo está activo de forma predeterminada.

Campos de solicitud (todos opcionales excepto name)

Crear un Agente desde su sitio web. Incluya scrape_urls y la plataforma leerá esas páginas y escribirá las instrucciones por usted. La respuesta le indica si esa generación comenzó, para que sepa si debe consultar el progreso del Agente.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Listing assistant",
    "language": "en",
    "instructions": "Answer questions about our listings and book viewings.",
    "goal": "Book a viewing"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Listing assistant",
    scrape_urls: ["https://example.com", "https://example.com/faq"],
  }),
});
const data = await res.json();
console.log(data.agent_id);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Listing assistant", "scrape_urls": ["https://example.com"]},
)
print(res.json()["agent_id"])

Respuesta (201)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "substrate_campaign_id": null,
  "agent_generation_queued": true
}

agent_generation_queued es true cuando la plataforma comenzó a escribir las instrucciones a partir de las páginas que proporcionó.

Un 400 significa que el cuerpo no era un objeto JSON, un campo fue rechazado o el Agente excede el tamaño de configuración que permite su plan. Un 403 significa que la cuenta no tiene permiso para usar una de las configuraciones que envió; por ejemplo, un nivel de IA que el proveedor de su cuenta no le ha otorgado.

Obtener un Agente #

GET /agents/{agentId}

Pase fields con una lista separada por comas para obtener solo lo que necesita, por ejemplo fields=name,active,goal. El id siempre se incluye, y los nombres que no existen en el Agente se ignoran en lugar de ser rechazados. Omítalo para obtener el documento completo.

cURL

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?fields=name,active", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agent } = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"fields": "name,active"},
)
agent = res.json()["agent"]

Un Agente que no existe en su cuenta devuelve 404.

Actualizar un Agente #

PUT /agents/{agentId} — envíe solo los campos que desea cambiar; todo lo demás se deja intacto.

Los ajustes anidados pueden abordarse hoja por hoja con una clave de puntos, por lo que "availability.monday" cambia solo el lunes y deja el resto de la semana intacto.

Notas

• Para cambiar el tipo de evento reservable en el que el Agente realiza reservas, envíe event_id (el id del evento, o null para borrarlo). Envíe event_ids con una matriz para vincular varios a la vez: el primero se convierte en el principal y [] desvincula todo. event_id y event_ids son mutuamente excluyentes, y el campo event en sí no puede escribirse directamente.
• enable_bookings debe ser un booleano real, y booking_provider debe ser uno de default, zenchef, formitable.
• Los campos de propiedad e identidad se ignoran, al igual que el estado de ejecución interno (progreso de generación y optimización).
• El enrutamiento no se establece aquí. Utilice PUT /entry-points/channel-defaults para hacer que el Agente responda a un canal, POST /agents/{agentId}/entry-points para reglas de palabras clave y comentarios, y PATCH /agents/{agentId}/active para pausarlo o reanudarlo.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer questions about our listings and always offer a viewing.",
    "anthropic_model": "standard"
  }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ "availability.monday": { start_time: "09:00", end_time: "17:00" } }),
});

Python

requests.put(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"goal": "Book a viewing within three messages"},
)

Respuesta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Un cuerpo vacío devuelve 400 con "No fields to update".

Actualizar ajustes del bot #

PUT /agents/{agentId}/bot-config: la forma específica de cambiar solo los ajustes de conversación.

Un Agente no tiene una sección de bot separada: sus ajustes se encuentran directamente en el Agente, por lo que los nombres de los campos aquí son los mismos que enviaría a PUT /agents/{agentId}. Este endpoint existe como la forma segura y enfocada de cambiar algunos de ellos. Se requiere al menos un campo.

Los nombres de los campos deben ser nombres simples aquí: letras, números, guiones bajos y guiones. No se aceptan rutas con puntos en este endpoint (a diferencia de PUT /agents/{agentId}), por lo que bot.goal se rechaza con un 400.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Book a viewing within three messages", "ai_speed": "thorough" }'

El texto largo cuenta para el tamaño de configuración que permite su plan, por lo que un conjunto de instrucciones muy grande puede ser rechazado con un 400.

Establecer horas activas #

PUT /agents/{agentId}/active-hours: las horas durante las cuales el Agente responde automáticamente. Fuera de esas ventanas, permanece en silencio.

Envíe un objeto availability con claves por día de la semana (monday a sunday). Cada día toma una única ventana de tiempo o una lista de ventanas, en formato HH:MM de 24 horas. Los días que omita conservarán lo que tenían, y cualquier clave que no sea un día de la semana será rechazada, por lo que un error tipográfico no puede pasar desapercibido.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

Respuesta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Una clave de día de la semana incorrecta devuelve 400: "Invalid availability keys: funday. Allowed keys: monday through sunday."

Pausar o reanudar un Agente #

PATCH /agents/{agentId}/active — activa o desactiva el Agente. Un Agente en pausa mantiene toda su configuración pero deja de responder inmediatamente; la reanudación surte efecto al instante.

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active", {
  method: "PATCH",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ active: false }),
});

Respuesta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "active": false }

active debe ser un booleano real; cualquier otro valor devuelve 400 con "active (boolean) is required".

Duplicar un Agente #

POST /agents/{agentId}/duplicate — crea una copia con su configuración preservada. La copia no envía nada hasta que le asignes un canal o un Punto de Entrada.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/duplicate?apiKey=YOUR_API_KEY"

Respuesta (201)

{ "success": true, "agent_id": "ag9WsX3cRfV6tGyH", "source_agent_id": "ag7HkQ2ZpLxR3mNb" }

Un duplicado cuenta para el límite de Agentes de tu plan exactamente igual que crear uno desde cero, por lo que se rechaza con 403 cuando la cuenta alcanza su límite.

Eliminar un Agente #

DELETE /agents/{agentId}

La eliminación se rechaza mientras el Agente siga vinculado a algo que dejaría de funcionar sin él: una difusión, un Punto de Entrada o (en cuentas antiguas) una campaña. La respuesta enumera lo que lo mantiene vinculado para que puedas desvincularlo primero y volver a intentarlo.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY"

Respuesta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Bloqueado (409)

{
  "success": false,
  "error": "Agent is still attached to one or more broadcast(s). Detach it first.",
  "blocking_campaign_ids": [],
  "blocking_broadcast_ids": ["bc5TgYhUj8IkOlPm"],
  "blocking_entry_point_ids": []
}

Borradores: revisa los cambios antes de publicarlos #

Las ediciones realizadas en el editor, y cualquier reescritura producida por Optimizar con IA, se mantienen como un borrador no publicado hasta que los publiques. El Agente activo sigue respondiendo con su configuración actual hasta ese momento.

Publicar el borrador #

POST /agents/{agentId}/publish-draft — mueve el borrador a la configuración activa y borra el borrador en el mismo paso.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/publish-draft?apiKey=YOUR_API_KEY"

Respuesta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "published_keys": ["instructions", "goal"] }

published_keys enumera los ajustes que se movieron del borrador al Agente activo, para que puedas mostrar qué cambió.

Comprueba que existe un borrador antes de realizar esta llamada. Publicar un Agente que no tiene borrador no es una llamada admitida y actualmente devuelve un 500 con un mensaje genérico, no uno específico. Para descartar un borrador, utiliza la opción de descartar a continuación.

Descartar el borrador #

POST /agents/{agentId}/discard-draft — descarta el borrador y deja la configuración activa exactamente como está. Es seguro llamarlo cuando no hay ningún borrador; no sucede nada.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/discard-draft?apiKey=YOUR_API_KEY"

Optimizar un Agente con IA #

POST /agents/{agentId}/optimize — reescribe la configuración del Agente a partir de sus comentarios (“sigue ofreciendo descuentos”, “las respuestas son demasiado largas”) y guarda la reescritura como un borrador en lugar de ponerla en funcionamiento.

Envíe user_feedback (una instrucción simple) o, al reaccionar a una respuesta incorrecta específica, thumbs_down_feedback junto con el thumbs_down_message ofensivo. Al menos uno de los dos debe contener texto.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Keep replies under three sentences." }'

Respuesta (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

El trabajo se ejecuta en segundo plano y la llamada regresa de inmediato. Lea el Agente con GET /agents/{agentId} y observe optimize_run.status; una vez que vuelva a Draft, la reescritura estará esperando como borrador del Agente. Revísela y luego publíquela o deséchela.

Solo se permite una ejecución a la vez por Agente; una segunda llamada mientras hay una en curso devuelve 409. Esto utiliza créditos de IA.

Reglas de etiquetado #

Una regla de etiquetado es una etiqueta más una descripción de cuándo se aplica. Durante una conversación, el Agente lee esa descripción y etiqueta al contacto cuando corresponde, que es como se activan las automatizaciones basadas en etiquetas.

El objeto de regla

Agregar una regla de etiquetado #

POST /agents/{agentId}/tags

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "hot-lead",
      "description": "Apply when the contact asks about pricing or wants to book a call.",
      "ai_can_remove": false
    }
  }'

Respuesta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "tag": { "name": "hot-lead", "...": "..." } }

Reemplazar una regla de etiquetado #

PUT /agents/{agentId}/tags/{tagId}: la regla se encuentra mediante el id de etiqueta en la ruta y se reemplaza por completo, no se fusiona, así que envíe la regla completa en lugar de solo la parte que está cambiando. La etiqueta a la que apunta se conserva incluso si omite tag_id, por lo que una edición no puede separar la regla de su etiqueta.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Apply only when the contact asks to book a call." } }'

Eliminar una regla de etiquetado #

DELETE /agents/{agentId}/tags/{tagId}: el Agente deja de aplicar esa etiqueta. La etiqueta en sí, y cualquier contacto que ya la tenga, permanecen intactos.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY"

Ambos puntos finales devuelven 404 cuando el Agente no existe o cuando no tiene ninguna regla para esa etiqueta.

Generar un conjunto de etiquetas con IA #

POST /agents/{agentId}/tags/generate: diseña un conjunto completo de reglas (los nombres de las etiquetas y la redacción de “aplicar cuando…” detrás de cada una) leyendo las propias instrucciones y el objetivo del Agente.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/generate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "merge" }'

Respuesta (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mode": "merge" }

El trabajo se ejecuta en segundo plano. Lea el Agente y observe tag_generation.status; las reglas en sí aterrizan en el tags del Agente. Solo una ejecución a la vez por Agente (409 en caso contrario), y utiliza créditos de IA.

Fuentes de conocimiento #

Las fuentes de conocimiento son las páginas y documentos que la plataforma ha leído para usted. Adjuntar una a un Agente le permite responder a partir de ese contenido.

De dónde provienen los ids de origen. Añada contenido con los puntos finales de la base de conocimientos: POST /kb-sources/url para una página, POST /kb-sources/file para un documento, POST /kb-sources/bulk-import para un sitio completo. Estos devuelven un source_id que usted consulta con GET /kb-sources/{sourceId} hasta que esté listo. POST /kb-sources/url también acepta autoLinkToAgentId, que adjunta la fuente a un Agente tan pronto como finaliza la importación, por lo que puede omitir la llamada de adjuntar a continuación.

Adjuntar fuentes de conocimiento #

POST /agents/{agentId}/kb-sources: envíe kb_source_ids con una lista para adjuntar un conjunto completo en una sola llamada (lo que desea después de rastrear un sitio), o kb_source_id para una sola. Envíe una u otra. Adjuntar algo que ya está adjunto no cambia nada.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"] }'

Respuesta (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "kb_source_id": "kb2QwErTyUi9OpAs",
  "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"]
}

Separar fuentes de conocimiento #

DELETE /agents/{agentId}/kb-sources/{kbSourceId} para uno, o POST /agents/{agentId}/kb-sources/bulk-remove con kb_source_ids para varios. La eliminación masiva es un POST porque la lista de identificadores viaja en el cuerpo.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources/bulk-remove?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs"] }'

Las fuentes en sí no se eliminan y permanecen disponibles para sus otros Agentes. Desvincular algo que no está vinculado no cambia nada.

Preguntas frecuentes #

Las preguntas frecuentes se gestionan en sus propios endpoints y se vinculan a un Agente desde allí: POST /faqs/{faqId}/link con { "agent_id": "ag7HkQ2ZpLxR3mNb" }, y POST /faqs/{faqId}/unlink para eliminarla de nuevo. Una pregunta frecuente puede ser compartida por cualquier número de Agentes. Consulte la API de FAQs.

Una pregunta frecuente solo es utilizada por los Agentes a los que está vinculada; crear una no es suficiente por sí solo.

Herramientas #

Funciones personalizadas #

POST /agents/{agentId}/custom-functions permite que el Agente llame a una de sus funciones personalizadas durante las conversaciones. Solo se pueden vincular funciones que pertenezcan a la misma cuenta, y vincular una que ya esté vinculada no cambia nada.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "cf7Hk2ZpLxR3mNbV" }'

DELETE /agents/{agentId}/custom-functions/{customFunctionId} la desvincula. La función en sí no se elimina y permanece disponible para sus otros Agentes.

Gestione las funciones en /custom-functions; consulte Funciones personalizadas para saber qué son.

Servidores MCP #

Un servidor MCP es un paquete de herramientas listo para usar que su Agente puede descubrir y llamar por sí mismo; consulte Conectar servidores MCP a su bot. Los servidores se registran una vez en la cuenta y luego se vinculan a los Agentes que deban utilizarlos.

Los servidores MCP requieren la función de funciones personalizadas en su plan. Sin ella, los endpoints de /mcp-servers a nivel de cuenta devuelven 403. Vincular un servidor ya registrado a un Agente no está restringido.

Registrar un servidor #

POST /mcp-servers

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://tools.example.com/mcp",
    "auth_header_value": "Bearer sk_live_xxx"
  }'

Respuesta (201)

{
  "success": true,
  "server_id": "ms4TgBnH7yUj2kLp",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }],
  "last_error": null,
  "server": { "server_id": "ms4TgBnH7yUj2kLp", "name": "Inventory", "...": "..." }
}

Al guardar, la plataforma se conecta al servidor y almacena en caché la lista de herramientas que ofrece. Un servidor al que no se puede acceder se guarda de todos modos, con el motivo en last_error y una lista de herramientas vacía; así puede registrarlo primero y solucionar la conectividad después.

Un auth_type de oauth2 guarda el registro con oauth_connected: false y sin herramientas: todavía no hay ningún token. La autorización de un servidor OAuth requiere un inicio de sesión en el navegador y se realiza desde el panel de control, no a través de la API.

Listar, actualizar y eliminar servidores #

• GET /mcp-servers — todos los servidores registrados, los más recientes primero, bajo servers.
• PUT /mcp-servers/{serverId} — envíe solo lo que desea cambiar. Cambiar la URL o los campos de autenticación vuelve a probar la conexión y actualiza la lista de herramientas almacenada en caché.
• DELETE /mcp-servers/{serverId} — elimina el registro y lo desvincula de todos los Agentes y campañas que lo tenían habilitado.

curl "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY"

Los secretos nunca regresan. Las respuestas llevan auth_header_value_set (un indicador true/false que dice que un valor está almacenado) en lugar de la credencial, y los tokens OAuth y los secretos de cliente permanecen en el lado del servidor. Todo lo demás se devuelve: name, url, enabled, auth_type, auth_header_name, tools, enabled_tools, tool_policies, oauth_connected, tools_cached_at, last_connected_at, last_error, created_at, updated_at.

Probar una conexión #

POST /mcp-servers/test-connection — se conecta a un servidor y enumera sus herramientas. Dos formas de llamarlo:

• con server_id — prueba la configuración guardada y actualiza su lista de herramientas almacenada en caché;
• con un url en línea (más auth_header_name / auth_header_value) — una prueba previa al guardado que no almacena nada.

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers/test-connection?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tools.example.com/mcp", "auth_header_value": "Bearer sk_live_xxx" }'

Respuesta (200)

{
  "success": true,
  "server_name": "Inventory tools",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }]
}

Un error de conexión no es un error HTTP; obtiene un 200 con success: false y un error que describe qué salió mal, para que pueda mostrarlo junto al campo que el operador está editando.

Adjuntar un servidor a un Agente #

Registrar un servidor no le da acceso a ningún Agente. Adjúntelo:

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "ms4TgBnH7yUj2kLp" }'

Respuesta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mcp_server_id": "ms4TgBnH7yUj2kLp" }

DELETE /agents/{agentId}/mcp-servers/{mcpServerId} lo separa de nuevo. El servidor en sí no se elimina y permanece disponible para sus otros Agentes. Adjuntar o separar algo que ya está en ese estado no cambia nada.

Biblioteca de medios #

La biblioteca de medios contiene los archivos que un Agente puede enviar durante una conversación: un menú, una lista de precios, una foto de producto. Un Agente puede tener un máximo de 50 elementos.

Listar archivos multimedia #

GET /agents/{agentId}/media-library

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY"

Respuesta (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "media_items": [
    {
      "id": "mi4RtY7uIoP1aSdF",
      "item_id": "mi4RtY7uIoP1aSdF",
      "media_home": "agent",
      "title": "Spring menu",
      "description": "Send when someone asks what is on the menu.",
      "ai_description": "A one-page menu listing seasonal dishes and prices.",
      "type": "document",
      "media_content_type": "application/pdf",
      "media_url": "https://storage.googleapis.com/...",
      "max_sends_per_conversation": 1,
      "created_at": 1700000000000
    }
  ]
}

Los elementos almacenados en el Agente aparecen primero, seguidos de cualquier elemento antiguo que aún esté almacenado en la campaña desde la que se creó el Agente; media_home (agent o campaign) indica cuál es cuál. Dentro de cada grupo, el más reciente aparece primero.

media_url caduca después de 7 días. Es el enlace de descarga creado cuando se subió el archivo; considere uno antiguo como caducado en lugar de roto, y vuelva a leer la lista para obtener un enlace nuevo.

Subir archivos multimedia #

POST /agents/{agentId}/media-library — el archivo se sube en línea como base64, hasta 10 MB. La llamada regresa una vez que el archivo está almacenado, así que permita un poco más de tiempo que para una solicitud normal. Tenga en cuenta que este cuerpo utiliza nombres de campo en camelCase.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "JVBERi0xLjQKJcfs...",
    "mimeType": "application/pdf",
    "fileName": "spring-menu.pdf",
    "title": "Spring menu",
    "description": "Send when someone asks what is on the menu.",
    "maxSendsPerConversation": 1
  }'

Dos cosas suceden automáticamente: un GIF animado se convierte a video para que se reproduzca en todos los canales, y la plataforma escribe un breve resumen de lo que realmente contiene el archivo para que el Agente sepa cuándo encaja.

Un 400 cubre campos faltantes, un tipo de archivo no admitido, un archivo vacío o demasiado grande, y alcanzar el límite de 50 elementos. Un 403 significa que la biblioteca multimedia está desactivada para la cuenta.

Actualizar un elemento multimedia #

PATCH /agents/{agentId}/media-library/{itemId} — solo metadatos. El archivo en sí no se puede reemplazar; suba un elemento nuevo y elimine el anterior. Este cuerpo utiliza snake_case: title, description, send_message, max_sends_per_conversation (un número entero no negativo, o null para borrar el límite).

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Summer menu", "max_sends_per_conversation": 2 }'

Respuesta (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "item_id": "mi4RtY7uIoP1aSdF",
  "campaign_id": "",
  "media_home": "agent"
}

Eliminar un elemento multimedia #

DELETE /agents/{agentId}/media-library/{itemId} — elimina el elemento y su archivo almacenado. Eliminar un elemento que ya no existe tiene éxito e informa deleted: false, por lo que la llamada es segura para reintentar.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY"

Generar mensajes de seguimiento #

POST /agents/{agentId}/template-generation — escribe los mensajes de seguimiento del Agente por usted (los recordatorios que envía cuando una conversación se queda en silencio), según el propósito del Agente.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

Hay dos formas en que esto regresa, y el campo target le indica cuál:

• target: "agent" con un 200 — los mensajes se escribieron durante la llamada y el resultado está en data. Léalos desde el follow_up_config del Agente. Este es el caso habitual.
• target: "campaign" con un 202 — el trabajo se puso en cola para la campaña nombrada en campaign_id. Observe el template_generation_status de esa campaña hasta que finalice.

cold_only necesita una campaña saliente y se rechaza con 409 (reason: "cold_only_requires_campaign") en un Agente que no tiene ninguna. Un 403 significa que los seguimientos automáticos no están activados para la cuenta. Esto utiliza créditos de IA, y un 400 con "Insufficient credits." significa que la cuenta se ha quedado sin ellos.

Enrutamiento de conversaciones a un Agente #

Un Agente solo responde a las conversaciones que le envía un Punto de entrada. Hasta que un canal tenga uno, el primer mensaje de alguien con quien nunca ha hablado se almacena, pero nadie lo recoge y ningún asistente responde.

Listar los Puntos de entrada de un Agente #

GET /agents/{agentId}/entry-points — las reglas de enrutamiento que envían conversaciones a este Agente, de la más reciente a la más antigua. Se devuelven tanto las reglas actuales como las retiradas; una regla retirada tiene enabled: false.

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"

Para los valores predeterminados de canal de toda la cuenta, incluido un canal configurado deliberadamente para que nadie responda, lea GET /entry-points/channel-defaults en su lugar.

Crear un Punto de entrada #

POST /agents/{agentId}/entry-points — el Agente en la ruta siempre gana, por lo que nunca se puede crear una regla para un Agente diferente al que aparece en la URL.

channels es obligatorio e indica qué canales cubre la regla; por ejemplo, whatsapp, whatsapp_web, instagram, messenger, telegram, sms, email, chat_widget o custom_channel. Las nuevas reglas están habilitadas a menos que indique lo contrario.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'

Respuesta (201)

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Qué regla gana cuando varias podrían hacerlo: una conversación en curso o una asignación manual mantiene al Agente que ya tiene; de lo contrario, las reglas de palabras clave superan a las reglas de comentarios, que superan a las reglas de seguidores, y un valor predeterminado de canal es el último recurso. Si estas reglas deciden algo todavía en una cuenta, se informa mediante GET /entry-points/routing-status.

Esta es la versión corta. La guía de la API de puntos de entrada cubre todas las reglas de escalafón, comentarios y seguidores, un agente por número de WhatsApp, y cómo cambiar o eliminar una regla. Consulta Puntos de entrada para conocer el concepto, y la API de canales para conectar el canal en sí.

Errores de la API de agentes de IA #

Los endpoints de agentes devuelven el sobre de error estándar:

{
  "success": false,
  "error": "Agent not found"
}

Los códigos compartidos que puede devolver cualquier endpoint — 401, 403 (su plan no incluye acceso a la API), 429 (límite de tasa) y 500 — se enumeran con orientación sobre reintentos en Errores y paginación.

Una nota sobre el explorador. Los endpoints de /agents están en la especificación OpenAPI publicada, por lo que puede explorar sus campos exactos y ejecutar solicitudes en vivo en la Referencia de la API. Los endpoints de /mcp-servers a nivel de cuenta también están en la especificación, por lo que puede explorarlos allí también.

Relacionado #

• Agentes de IA: qué es un agente, en lenguaje sencillo.
• Puntos de entrada: cómo se dirigen las conversaciones a un agente.
• API de preguntas frecuentes: cree y vincule el conocimiento con el que responde su agente.
• API de canales: conecte los canales en los que responde un agente.
• Conectar servidores MCP a su bot · Funciones personalizadas
• Referencia de la API: el explorador de endpoints interactivo completo.