# Uso del agente como servicio Web

## Enviar un mensaje al agente 

Al enviar el mensaje (en nombre del usuario), se iniciará o continuará una conversación existente.

Solicitud

```
Method: POST

Headers

Authorization: Bearer <Código de seguridad del agente>
Content-Type: application/json; charset=utf-8

End point: https://agent.induxsoft.net/svc/{agent_id}/

Payload

{
	"chat_id":"",
	"chat_topic":"",
	"context_var_id":"Identificador de contexto variable (opcional)",
	"user_sid":"Valor del token de sesión del usuario",
	"user_name":"Nombre visible del usuario (opcional)",
	"user_phone":"Teléfono visible del usuario (opcional)",
	"user_email":"Correo electrónico del usuario (opcional)",
	"channel":"Un identificador del canal de comunicaciones (opcional)",
	"context":"Instrucciones adicionales al prompt (opcional)",
	"file":"datos del archivo (base 64) (opcional)",
	"filename":"Nombre del archivo (requerido si se ha establecido file o fileurl)",
	"fileurl":"Una URL para obtener un archivo, es mutuamente excluyente con file",
	"message":"Mensaje del usuario",
	"latitude":valor de latitud en caso de enviar una coordenada (opcional),
	"longitude":valor de longitud en caso de enviar una coordenada (opcional),
    "params":{... Conjunto de pares clave/valor que se pasarán como parámetros a herramientas y contextos variables ... },
	"format":"text/html/json (el valor predeterminado es text)"
}

```

Respuesta exitosa del servicio

```
{
	"success":true,
	"data":
	{
		"chat_id":"Id de la conversación",
		"response":"Respuesta del agente",
		"download":"Url para descarga de archivo si aplica",
		"isbusy":true/false
	}
}
```

Respuesta de error del servicio

```
{
	"success":false,
	"message":"Mensaje descriptivo del error"
}
```

## Usar agente como herramienta

### Solicitud

**Method:** `POST`

**Endpoint** `https://agent.induxsoft.net/astool/{agent_id}/`

### Headers

```http
Authorization: Bearer <Código de seguridad del agente>
Content-Type: application/json; charset=utf-8

```

Payload herramienta
```
{
  "intention": "Id de la intención",
  "preliminary_answer": "Respuesta preliminar del LLM",
  "original_question": "Pregunta o mensaje original del usuario",
  "reformulated_question": "Pregunta o mensaje del usuario reformulado por el LLM",
  "agent_id": "Id del agente",
  "agent_name": "Nombre del agente",
  "chat_id": "Identificador de la conversación que invoca la herramienta",
  "source_url": "URL desde la que el agente hace la solicitud (opcional)",
  "user_sid": "Token de sesión que fue suministrado al agente para ser validado",
  "user": "Id del usuario si está autenticado",
  "user_name": "Nombre para mostrar del usuario",
  "data": {
    "...": "Objeto con los datos definidos en la intención"
  },
  "params": {
    "...": "Pares clave/valor proporcionados por la aplicación o configuración"
  }
}
```

Respuestas del servicio

Respuesta exitosa
```
Cadena: respuesta del agente invocado
```

Respuesta de error
```
Cadena: error ocurrido
```

*Consideraciones*:
- Los datos contenidos en `params` se envían en la carga útil del agente.
- Los datos de data se integran dentro de params.
- Si algún campo de `data` o `params` es requerido por el agente, se eleva al primer nivel del payload final.


*Ejemplo de transformación*

Payload esperado por el agente
```
{
  "chat_topic": "",
  "context_var_id": "",
  "user_sid": "",
  "user_name": "",
  "user_phone": "",
  "user_email": "",
  "channel": "",
  "context": "",
  "file": "",
  "filename": "",
  "fileurl": "",
  "message": "",
  "latitude": "",
  "longitude": "",
  "format": ""
}

data
{
  "chat_topic": "simple prueba",
  "context": "Simple contexto"
}

params
{
  "user_email": "miemail@email.com"
}

Payload final
{
  "chat_topic": "simple prueba",
  "context_var_id": "",
  "user_sid": "",
  "user_name": "",
  "user_phone": "",
  "user_email": "miemail@email.com",
  "channel": "",
  "context": "Simple contexto",
  "file": "",
  "filename": "",
  "fileurl": "",
  "message": "",
  "latitude": "",
  "longitude": "",
  "format": ""
}
```

*Reglas adicionales*

- Si un campo existe tanto en data como en params, se prioriza el valor de data.
- Si no existe el campo message en data, entonces: `message = data`



## Toma de control y envío de mensajes al usuario

A través de este punto final es posible tomar el control humano de la conversación y enviar mensajes.

```
Method: POST

Headers

Authorization: Bearer <Código de seguridad del agente>
Content-Type: application/json; charset=utf-8

End point: https://agent.induxsoft.net/svc/{agent_id}/handoff/{chat_id}/

Payload:
{
	"ai_control":true,
	"message":
	{
		"text": "Texto del mensaje humano",
		"human":"Nombre o identificador del humano que envía el mensaje",
		"silence": "true/false - Indica si el mensaje no debe responderse por el canal de la solicitud (predeterminado: false)",
		"attatchments":
		[
			{
				"filename":"nombre_archivo",
				"content":"Base 64 del binario del archivo"
			},...
		]
	}
}

Response:
{
	"success":true/false
	"message":"Mensaje de error en caso de que success=false"
	"data": //Solo si en la solicitud se indicó un mensaje para el usuario
	{
		"id":"Id del mensaje enviado",
		"text":"Texto del mensaje enviado",
	}
}

```

Explicaciones:

El campo ai_control determina si después de la solicitud el agente continúa con el control (respondiendo) o no,
esto permite al humano tomar el control de la conversación desactivando al agente.

El campo message permite enviar un mensaje al usuario, si se envía un mensaje puede incluir el campo ai_control o no según lo que necesite.

El campo attatchments del mensaje es opcional.

Ejemplos:
- Si quiere tomar el control, debe enviar ai_control=false (para desactivar las respuestas del agente) y opcionalmente un mensaje.
- Si quiere volver a ceder el control al agente, debe enviar ai_control=true y opcionalmente un mensaje.
- Si quiere únicamente enviar un mensaje (ya sea que el agente esté en control o no), solo incluya el campo message

## Susurro

Un susurro es información contextual que le servirá al agente para responder mejor en el siguiente turno.

```
Method: POST

Headers

Authorization: Bearer <Código de seguridad del agente>
Content-Type: application/json; charset=utf-8

End point: https://agent.induxsoft.net/svc/{agent_id}/whisper/{chat_id}/

Payload:
{
	"text":"Texto del susurro para el agente"
}

Response:
{
	"success":true/false
	"message":"Mensaje de error en caso de que success=false"
}
```

## Información de la conversación

Devuelve información de una conversación activa

No se requiere autenticación porque se espera que se presente el Id de una conversación (chat_id) que debe estar abierta.

```
Method: GET

Headers

Content-Type: application/json; charset=utf-8

End point: https://agent.induxsoft.net/svc/{agent_id}/{chat_id}/

Response:
{
	"success":true/false, //Devolverá false si el chat_id no es válido o la conversación ha finalizado
	"data":
	{
		"channel":"Canal en el que está la conversación",
		"last_message_timestamp":"yyyyy-dd-mmThh:mm:ss Fecha y hora del último mensaje (recibido o enviado)",
		"minutes_elapsed": Un entero que indica los minutos que han transcurrido desde el último mensaje al momento actual,
		"last_message_id":"Id del último mensaje",
		"ai_control":true/false //Indica si el agente está en control o no de la conversación
	},
	"message":"Mensaje de error en caso de que success=false"
}
```

## Recuperar mensajes

Devuelve los mensajes de una conversación abierta según un criterio específico

No se requiere autenticación porque se espera que se presente el Id de una conversación (chat_id) que debe estar abierta.

```
Method: GET

Headers

Content-Type: application/json; charset=utf-8

End point: https://agent.induxsoft.net/svc/{agent_id}/{chat_id}/messages/?after={message_id}|before={message_id}&limit={num}|last={num}&format=text|html

Response:
{
	"success":true/false,
	"data":
	[
		{
			"id":"Id del mensaje",
			"text":"Texto del mensaje",
			"html":"Versión en html del mensaje si se ha indicado format=html",
			"whisper":"Susurro si lo hubiese",
			"role":"user/agent/human",
			"human":"Nombre o identificador si el mensaje fue escrito por un humano que no es el usuario",
			"timestamp":"yyyyy-dd-mmThh:mm:ss"
		},...
	],
	"message":"Mensaje de error en caso de que success=false"
}
```

Parámetros

Debe elegirse entre after, before y last para situar el punto de partida del que se devolverán los mensajes.

- before={message_id}. Devolverá los mensajes anteriores al mensaje indicado
- after={message_id}. Devolverá los mensajes posteriores al mensaje indicado
- last={num}. Devolverá la cantidad de los últimos mensajes establecida

Si se usa before o after, puede incluirse limit para indicar la cantidad de mensajes a devolver. Si se omite limit, se asume un máximo de 50

El parámetro format indica si se incluirá la versión html de cada mensaje, el valor predeterminado es text (si se omite el parámetro), en cuyo caso el campo html de la respuesta podría no existir, ser nulo o una cadena vacía.

Ejemplo para obtener los 10 mensajes posteriores a un mensaje dado:

```
https://agent.induxsoft.net/svc/{agent_id}/{chat_id}/messages/?after={message_id}&limit=10
```

## Conversaciones de un agente
Obtiene la lista de conversaciones asociadas a un agente específico.

```
Method: GET

Headers

Authorization: Bearer <Código de seguridad del agente>
Content-Type: application/json; charset=utf-8

End point: https://agent.induxsoft.net/svc/{agent_id}/conversations/?after={chat_id}|before={chat_id}&limit={num}|last={num}

Response:
{
	"success":true/false,
	"data":
	[
		{
			"chat_id": "ID de la conversación",
			"username": "Nombre del usuario (si existe)",
			"userphone": "Teléfono del usuario (si existe)",
			"usermail": "Correo electrónico del usuario",
			"channel": "Canal de la conversación",
			"messages": "Cantidad de mensajes de la conversación",
			"lastchat": "Fecha del último mensaje",
			"finish": "Fecha de finalización de la conversación",
			"topic": "Título o ID del tema",
			"start": "Fecha de inicio de la conversación",
			"revision": "true | false",
			"uid": "ID del perfil (si existe)"
		},...
	],
	"message":"Mensaje de error en caso de que success=false"
}
```

Parámetros

Debe especificarse uno de los siguientes parámetros para definir el punto de partida desde el cual se devolverán las conversaciones.
Si no se indica ninguno, se devolverán todas las conversaciones encontradas.

- before={chat_id}. Devolverá las conversaciones anteriores a la conversación indicado
- after={chat_id}. Devolverá las conversaciones posteriores a la conversación indicado
- last={num}. Devolverá la cantidad de las conversaciones establecida.

#### Parámetros opcionales de filtrado

- fi. fecha inicial del filtro, sí se omite se considera la fecha actual.
- ff. fecha final del filtro, sí se omite se considera la fecha actual.
- topic. ID del tema.
- channel. ID del canal.
- limit. Cantidad máxima de registros a devolver.

Cuando se utiliza before o after, puede incluirse el parámetro limit para indicar la cantidad de conversaciones a devolver.

Si se omite limit, se asumirá un máximo de 50 registros.

## Inicio proactivo de conversaciones

Algunos canales (como WhatsApp) permiten el inicio proactivo de conversaciones, es decir que el primer mensaje sea enviado por medio del agente de IA.

[Vea especificación del  servicio de inicio proactivo](https://docs.induxsoft.net/es/iae/agentes/servicio-web-send.md)