> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Ejecutar acciones de aplicaciones durante las conversaciones

> Convierte una acción de una aplicación conectada, como añadir una fila a una hoja de cálculo, en una herramienta que tu asistente usa en llamadas, chats y correo

Una herramienta de acción de aplicación permite que un asistente ejecute una acción en una aplicación conectada a tu espacio de trabajo mientras la conversación sigue en curso. Por ejemplo, añadir una fila a una hoja de Google Sheets o crear un contacto en HubSpot. Eliges la aplicación, la conexión y la acción, y Famulor convierte los campos de la acción en una herramienta con parámetros reales. No necesitas tu propio endpoint de API ni una automatización.

> [!NOTE]
>
> Las herramientas de acción de aplicación están en beta. Los propietarios y administradores las ven en cuanto el interruptor **Funciones beta** está activado en [Ajustes → Espacio de trabajo](https://docs.famulor.io/es/settings/workspaces.md), y el plan del espacio de trabajo debe incluir automatizaciones. Los demás miembros ven las herramientas de acción de aplicación asignadas, pero no pueden cambiarlas.

## Cómo funciona una herramienta de acción de aplicación

Una peluquería quiere guardar en una hoja de cálculo las solicitudes de devolución de llamada. Crea una herramienta de acción de aplicación para la acción de Google Sheets «Add row». La hoja de cálculo y la pestaña son valores fijos, el asistente rellena el nombre y la solicitud de quien llama, y el número de teléfono procede del identificador de llamadas. Antes de escribir la fila, el asistente lee los datos en voz alta y pide a quien llama que los confirme.

La herramienta aparece en **Herramientas de agente** junto a tus demás herramientas, y la asignas a asistentes como cualquier otra. Funciona en todos los canales de conversación:

* llamadas telefónicas, llamadas web y llamadas de WhatsApp
* chat web, también en Test Chat
* todos los [canales de mensajería](https://docs.famulor.io/es/channels/messaging.md), como WhatsApp, SMS, Telegram o Slack
* [correo electrónico](https://docs.famulor.io/es/channels/email.md), tanto la dirección propia del asistente como los buzones conectados

## Elegir el tipo de herramienta adecuado

Una herramienta de acción de aplicación cubre exactamente una acción en una aplicación. Para todo lo demás encaja mejor otro tipo de herramienta:

| Necesitas | Usa |
| - | - |
| Una acción en una aplicación conectada | Una herramienta de acción de aplicación (esta página) |
| Una solicitud a tu propio endpoint HTTP | Una [herramienta de API](https://docs.famulor.io/es/api/tools-and-webhooks.md#herramientas-de-api) |
| Varios pasos, condiciones o aplicaciones en una ejecución | Una automatización [llamada desde la conversación](https://docs.famulor.io/es/automations/overview.md#llamar-a-una-automatización-desde-una-conversación) |

Para una sola acción, una herramienta de acción de aplicación es más rápida que una automatización invocable. El asistente envía cada campo directamente, así que ningún paso de IA adicional tiene que extraer los valores de un texto libre.

## Antes de empezar

Comprueba primero estos requisitos:

* Eres propietario o administrador del espacio de trabajo.
* El interruptor **Funciones beta** está activado en **Ajustes → Espacio de trabajo**.
* El plan del espacio de trabajo incluye automatizaciones, y su límite **Herramientas y MCP** tiene sitio para otra herramienta.
* La aplicación está conectada en **Automatizaciones → Conexiones**. También puedes conectarla mientras creas la herramienta.

## Crear una herramienta de acción de aplicación

**1. Elegir la aplicación y la acción**

Abre **Herramientas de agente** y selecciona **Nueva herramienta → App (Beta)**. También puedes empezar desde la tarjeta **Apps** en **Conectores de agente**, donde el logo de una app abre directamente esa app, o seleccionar **Usar en el asistente** junto a una app en **Automatizaciones → Conexiones**. El editor muestra tus apps conectadas. Para añadir otra app, selecciona **Conectar una app**: se abre la misma lista de apps que en las automatizaciones y vuelves aquí después de iniciar sesión. Después elige la acción. Si la aplicación tiene varias conexiones, elige una en **Conexión**.

**2. Nombrar la herramienta e indicar cuándo usarla**

**Nombre** viene rellenado, por ejemplo `google_sheets_add_row`. En **Usar cuando**, describe la situación en la que el asistente debe llamar a la herramienta, por ejemplo «Cuando quien llama pide que le devuelvan la llamada». Usa al menos 10 caracteres. Una frase concreta funciona mejor que una etiqueta corta.

**3. Elegir de dónde sale cada valor**

Cada campo de la acción tiene el ajuste **Valor de**, que se describe en la sección siguiente. Los campos obligatorios aparecen primero. Los opcionales empiezan en **Desactivado** dentro de **Más campos**.

**4. Decidir si el asistente pregunta primero**

En las acciones que cambian datos, **Preguntar primero** está activado. Déjalo activado, salvo que el cambio no necesite confirmación. La sección «Preguntar primero» más abajo explica cómo funciona.

**5. Revisar la vista previa y probar**

**Lo que ve el asistente** muestra la herramienta exactamente como la recibe el asistente. Pruébala en **Prueba** antes de guardar, como se describe más abajo.

**6. Guardar y asignar**

Selecciona **Crear herramienta** y después [asigna la herramienta](https://docs.famulor.io/es/assistants/agent-tools.md#installed) a los asistentes. En los ajustes de un asistente, **Avanzado → Herramientas → Agregar herramienta** muestra tus **Aplicaciones conectadas**: selecciona una para abrir el mismo editor, o selecciona **Conectar una app** para conectar primero otra app. La herramienta se asigna cuando seleccionas **Añadir al asistente**. Una herramienta de acción de aplicación todavía no puede ser un nodo **Tool** en un [Flow](https://docs.famulor.io/es/flow-builder/nodes.md#tool); asígnala al asistente en su lugar.

## Elegir de dónde sale cada valor

**Valor de** decide quién aporta el valor de un campo:

| Valor de | El valor viene de | Úsalo para |
| - | - | - |
| **IA** | El asistente, a partir de la conversación | Datos que da el cliente, como un nombre, una solicitud o una fecha preferida |
| **Valor fijo** | Lo que escribes, enviado en cada ejecución | Identificadores de una hoja de cálculo, un calendario, una lista o un pipeline, y etiquetas fijas |
| **Variable** | Una variable de la conversación, como **Número de quien llama** | El número de quien llama, el correo del cliente o una variable del asistente |
| **Desactivado** | Nadie: el campo no se envía | Campos opcionales que no necesitas |

Para los campos **IA**, Famulor escribe una descripción a partir de la información de la aplicación sobre el campo, con el formato esperado, como `YYYY-MM-DD`, y un ejemplo. Escribe tu propia descripción para reemplazarla. Hasta 12 campos pueden usar **IA**. Quédate en 8 o menos: con menos campos, las llamadas son más rápidas y fiables.

El asistente nunca ve los campos con **Valor fijo** ni **Variable** y no puede cambiarlos. Un texto fijo puede contener [variables](https://docs.famulor.io/es/assistants/variables.md) como `{{caller_number}}` y los valores de los campos IA, escritos con el nombre de parámetro que muestra **Lo que ve el asistente**, por ejemplo `{{start_time}}`. Si pegas un enlace a un elemento de Google Sheets, Docs, Drive, Notion o Airtable, Famulor conserva solo su identificador.

Además, se aplican estas reglas a los campos:

* Los campos de teléfono empiezan con la variable **Número de quien llama**. En los canales de mensajería contiene el número de teléfono del contacto.
* Los campos obligatorios no pueden estar en **Desactivado**.
* Algunos campos esperan filas de tabla, por ejemplo los valores de una nueva fila de una hoja de cálculo o los asistentes a un evento. Muestran **Columnas**. Para una fila de hoja de cálculo, selecciona **Añadir columna** para cada valor y ponle nombre a la columna. En una lista como la de asistentes, la aplicación define las columnas, por ejemplo Email y Name; selecciona **Añadir fila** para cada entrada. Elige **IA**, **Valor fijo** o **Variable** para cada celda. Una columna obligatoria necesita un valor en cada fila.
* En una lista como la de asistentes, las columnas opcionales empiezan en **Desactivado**. Actívalas en una fila cuando las necesites. Las celdas de número y de sí/no aceptan **IA** o **Valor fijo**.

**Lo que ve el asistente** muestra el nombre de la herramienta, su descripción y todos los campos IA. Los valores fijos y las variables aparecen como no visibles para el asistente. La descripción puede tener hasta 900 caracteres. Con el icono de lápiz escribes tú mismo la descripción. Las frases sobre confirmar cambios y sobre resultados desconocidos siempre se mantienen al final.

## Preguntar primero

En las acciones que cambian datos, como añadir una fila o crear un contacto, **Preguntar primero** está activado de forma predeterminada. Las acciones que solo leen datos nunca preguntan. Con **Preguntar primero** activado, un cambio funciona así:

1. El asistente llama a la herramienta. Todavía no cambia nada: Famulor devuelve un resumen de los valores.
2. El asistente lee el resumen al cliente y le pregunta si es correcto.
3. El asistente vuelve a llamar a la herramienta con los mismos valores. Esta llamada ejecuta la acción en la aplicación si se cumple la condición del canal:
   * En mensajería y correo electrónico, el cliente ha enviado un mensaje nuevo desde el resumen.
   * En llamadas y en el chat web, han pasado al menos 4 segundos desde la primera llamada. Ahí Famulor no puede comprobar si el cliente respondió.

Una llamada demasiado temprana no cambia nada, y el asistente recibe la indicación de esperar la respuesta del cliente. Si un valor cambia entretanto, el asistente lee los datos nuevos y vuelve a preguntar. Un cambio preparado caduca a los 10 minutos en llamadas y en el chat web, a las 72 horas en correo electrónico, también en los buzones conectados, y a las 24 horas en los demás canales de mensajería.

> [!WARNING]
>
> En llamadas y en el chat web, **Preguntar primero** solo impone una pausa: un cambio puede ejecutarse a los 4 segundos aunque el cliente no haya respondido. En mensajería y correo electrónico, un cambio solo se ejecuta después de un mensaje nuevo del cliente. En ningún canal es **Preguntar primero** un registro de consentimiento: Famulor no comprueba qué respondió el cliente ni guarda una prueba de acuerdo aparte. Cuando necesites un consentimiento documentado, por ejemplo para un contrato o un pago, recógelo con un proceso pensado para ello.

Puedes desactivar **Preguntar primero** para un cambio que no necesite confirmación. El asistente cambia entonces los datos en la aplicación sin leerlos antes.

## Probar antes de usar

Prueba cada herramienta antes de asignarla a un asistente que habla con clientes. En **Prueba**, introduce valores de ejemplo para los campos IA y las variables, y selecciona **Ejecutar prueba**:

* Las acciones que leen datos se ejecutan de verdad.
* Las acciones que cambian datos se ejecutan primero como simulacro: no cambia nada y ves lo que el asistente leería al cliente. Selecciona **Ejecutar de verdad** y confirma para hacer el cambio en la aplicación.

El resultado muestra si la ejecución salió bien, cuánto tardó y exactamente qué recibe el asistente. En las llamadas, quien llama espera mientras se ejecuta la acción, así que fíjate en la duración. Después, prueba la herramienta en una llamada de prueba o en Test Chat con el asistente al que está asignada.

## Lo que recibe el asistente

Famulor acorta cada resultado antes de que el asistente lo lea. Elimina los identificadores internos, los números de versión y los valores que parecen secretos. Además, corta los textos a 500 caracteres y las listas a 10 elementos, y limita el resultado completo a 2.000 caracteres.

En **Avanzado → Resultado**, elige **Campos seleccionados** para conservar solo los campos que escojas de un resultado de prueba correcto. Mediante la API, `result_config.max_chars` sube el límite a 3.500 caracteres. El asistente recibe los resultados marcados como datos externos, no como instrucciones.

## Límites

| Límite | Valor |
| - | - |
| Tiempo por ejecución | 12 segundos; la aplicación debe responder en 8 segundos |
| Campos IA por herramienta | 12 |
| Descripción de la herramienta | 900 caracteres |
| Texto por valor | 4.000 caracteres |
| Resultado para el asistente | 2.000 caracteres, hasta 3.500 mediante la API |
| Ejecuciones por herramienta | 60 por minuto |
| Ejecuciones por espacio de trabajo | 300 por minuto |
| Ejecuciones por herramienta en una conversación | 15 por minuto, de ellas hasta 5 cambios (leer los datos en voz alta no es un cambio) |
| Acciones que eliminan datos | Aún no disponibles |

Si la aplicación no responde a tiempo, lo que ocurre depende de la acción. Una acción que lee datos no se ha ejecutado, y el asistente puede volver a intentarlo. En un cambio, el resultado es desconocido: el asistente no lo reintenta y le dice al cliente que el equipo lo revisará.

## Editar, reconectar o eliminar una herramienta

Abre la herramienta en **Herramientas de agente** para cambiar sus campos, **Usar cuando** o **Preguntar primero**. **Ejecuciones** muestra las últimas ejecuciones de la herramienta en todos los canales, también en mensajería, correo electrónico y pruebas. Un cambio preparado que espera al cliente y un simulacro no aparecen ahí, porque no se ejecutó nada en la aplicación. Las ejecuciones fallidas y las de resultado desconocido aparecen como errores. Para usar otra acción, crea una herramienta nueva.

* Puedes cambiar la herramienta a otra conexión de la misma aplicación.
* Cuando una conexión caduca, la herramienta muestra **Reconectar** y no se ejecuta hasta que vuelvas a conectarla. Selecciona **Reconectar** e inicia sesión de nuevo: Famulor renueva la misma conexión y te devuelve a la herramienta. Si la herramienta tiene cambios sin guardar, Famulor te pregunta antes si quieres descartarlos. Si el inicio de sesión falla, la herramienta muestra el error y de nuevo **Reconectar**.
* No puedes eliminar una conexión que usan herramientas de acción de aplicación. Cambia antes esas herramientas a otra conexión o elimínalas.
* Para eliminar una herramienta de acción de aplicación, quítala primero de cada asistente que la use. Después elimínala como cualquier otra.
* Las herramientas de acción de aplicación no se pueden mover a otro espacio de trabajo. Vuelve a crear la herramienta en el otro espacio de trabajo.

## API, MCP, CLI y SDK

Puedes crear, leer, cambiar y probar herramientas de acción de aplicación sin el panel. Cada solicitud requiere un acceso de propietario o administrador. Listar y leer acciones, así como crear, cambiar o probar una herramienta, requieren además un plan con automatizaciones. Listar y leer acciones requiere el alcance `automations:read`, leer una herramienta `assistants:read`, y crear, cambiar o probar una herramienta requiere tanto `assistants:write` como `automations:write`. Como en el panel, crear una herramienta también requiere **Funciones beta**.

| API | MCP | CLI | SDK |
| - | - | - | - |
| `GET /api/v1/automations/connections/{id}/actions` | `list_app_actions` | `famulor list-app-actions <id>` | `client.api.listAppActions({ path: { id } })` |
| `GET /api/v1/automations/connections/{id}/actions/{action}` | `get_app_action` | `famulor get-app-action <id> <action>` | `client.api.getAppAction({ path: { id, action } })` |
| `POST /api/v1/tools/app-actions` | `create_app_action_tool` | `famulor create-app-action-tool --input tool.json` | `client.api.createAppActionTool({ body })` |
| `GET /api/v1/tools/app-actions/{toolId}` | `get_app_action_tool` | `famulor get-app-action-tool <toolId>` | `client.api.getAppActionTool({ path: { toolId } })` |
| `PATCH /api/v1/tools/app-actions/{toolId}` | `update_app_action_tool` | `famulor update-app-action-tool <toolId> --input patch.json` | `client.api.updateAppActionTool({ path: { toolId }, body })` |
| `POST /api/v1/tools/app-actions/{toolId}/test` | `test_app_action_tool` | `famulor test-app-action-tool <toolId> --input test.json` | `client.api.testAppActionTool({ path: { toolId }, body })` |

Las herramientas de acción de aplicación también aparecen en `GET /api/v1/tools`, con un resumen en `app_action`. Asígnalas con `PUT /api/v1/assistants/{id}/tools` o indica `assistant_id` al crearlas; un asistente desconocido devuelve `404` antes de que se cree la herramienta. `GET /api/v1/tools/{id}/runs` y la herramienta MCP `list_tool_runs` devuelven las ejecuciones que aparecen en **Ejecuciones**. Quita una herramienta de sus asistentes y después elimínala con `DELETE /api/v1/tools/{id}`. El `PATCH /api/v1/tools/{id}` general sigue permitiendo cambiar el nombre de una herramienta o activarla y desactivarla; cualquier otro cambio por esa vía devuelve `409`. La prueba general, `POST /api/v1/tools/test` o `test_tool`, también devuelve `409` para una herramienta de acción de aplicación.

### Crear una herramienta con la API

Primero, lista las acciones de una conexión. `q` busca por nombre. Las acciones que eliminan datos no aparecen en la lista.

```bash theme={null}
curl "https://app.famulor.io/api/v1/automations/connections/CONNECTION_ID/actions?q=row" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Lee los detalles de la acción elegida con `get-app-action`. Muestran los `fields` de la acción, cada uno con su `key`, su `path`, su `param` y un `mode` sugerido. En la solicitud de creación, envía solo los campos que quieras cambiar, identificados por su `path` o su `key`. Puedes definir `mode`, `value`, `variable` y `description`; los demás campos mantienen su ajuste sugerido. Esta solicitud crea la herramienta y la asigna a un asistente:

```json theme={null}
{
  "connection_id": "CONNECTION_ID",
  "action": "ACTION_ID",
  "use_when": "Cuando quien llama pide que le devuelvan la llamada.",
  "confirmation": "ask_first",
  "assistant_id": "ASSISTANT_ID",
  "fields": [
    { "key": "spreadsheet_id", "mode": "fixed", "value": "SPREADSHEET_ID" },
    { "key": "phone", "mode": "variable", "variable": "caller_number" }
  ]
}
```

Las claves de los campos dependen de la acción. `confirmation` es `ask_first` o `none`; las acciones que leen datos nunca preguntan. Para asegurarte de que la acción no ha cambiado desde que la leíste, envía también su `version`: la solicitud falla si la acción tiene una versión más reciente. Guarda el cuerpo como `tool.json` y envíalo con `famulor create-app-action-tool --input tool.json` o `POST /api/v1/tools/app-actions`.

Después, prueba la herramienta. `values` contiene valores de ejemplo para los campos IA y las variables. Usa el `param` de cada campo, es decir, el nombre de parámetro que ve el asistente, no su `key`. Los dos suelen ser distintos: el campo `startTime` tiene el `param` `start_time`, y una columna toma su nombre de columna, por ejemplo `name`. En un campo de variable también sirve el nombre de la variable, como `caller_number`:

```json theme={null}
{
  "values": { "name": "Anna Weber", "request": "Devolver la llamada por una cita de color" },
  "mode": "dry_run"
}
```

`mode` es `dry_run`, el valor predeterminado, o `live`. En una acción que cambia datos, una prueba real necesita además `"confirm_write": true` y cambia datos reales en la aplicación. La respuesta contiene `model_text`, el texto exacto que recibiría el asistente. En una acción que cambia datos, `read_back` indica lo que el asistente leería en voz alta, también en una simulación.

## Próximos pasos

> [card] [Agent Tools](https://docs.famulor.io/es/assistants/agent-tools.md)
>
> Asigna, edita y supervisa todas las herramientas de tu espacio de trabajo

> [card] [App Catalog](https://docs.famulor.io/es/automations/app-catalog.md)
>
> Conecta aplicaciones y descubre qué pueden hacer en las automatizaciones


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.