> For the complete documentation index, see [llms.txt](https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/referencias-tecnicas/api/tools.md).

# Herramientas

Esta documentación describe todas las herramientas disponibles en Taína para interactuar con el catálogo de servicios gubernamentales.

Taína expone 8 herramientas especializadas que permiten al agente acceder a información específica sobre servicios gubernamentales dominicanos. Cada herramienta está optimizada para un tipo particular de consulta.

### Herramientas disponibles

1. **`list_services`** - Búsqueda de servicios
2. **`get_service_overview`** - Información general
3. **`list_service_variations`** - Categorías y costos
4. **`get_service_locations`** - Ubicaciones y horarios
5. **`get_service_digital_channel`** - Canales online
6. **`get_service_contact`** - Información de contacto
7. **`ask_knowledge_base`** - Búsqueda semántica
8. **`get_current_date`** - Fecha actual

## 1. list\_services

Busca servicios gubernamentales por nombre, institución o palabra clave.

### Firma

```python
async def list_services(
    nombre: Optional[str] = None,
    institucion: Optional[str] = None,
    keyword: Optional[str] = None,
    limit: int = 5,
) -> str
```

### Parámetros

| Parámetro     | Tipo            | Descripción                                | Ejemplo                 |
| ------------- | --------------- | ------------------------------------------ | ----------------------- |
| `nombre`      | `Optional[str]` | Nombre del servicio (coincidencia parcial) | `"licencia"`            |
| `institucion` | `Optional[str]` | Nombre de la institución                   | `"INTRANT"`             |
| `keyword`     | `Optional[str]` | Búsqueda de texto libre                    | `"renovación conducir"` |
| `limit`       | `int`           | Número máximo de resultados (default: 5)   | `10`                    |

### Valor de retorno

JSON string con servicios encontrados:

```json
{
  "results": [
    {
      "service_id": "163",
      "nombre": "Renovación Licencia de Conducir",
      "institucion": "INTRANT",
      "nombres_alternativos": ["Renovación de Licencia", "Licencia de Conducir"],
      "tipos_disponibles": ["servicio_principal", "variacion_servicio", "ubicaciones"],
      "score": 3
    }
  ],
  "count": 1
}
```

### Ejemplos de uso

```python
# Buscar por institución
result = await list_services(institucion="INTRANT")

# Buscar por nombre parcial
result = await list_services(nombre="licencia")

# Búsqueda por palabra clave
result = await list_services(keyword="renovación conducir")

# Combinar criterios
result = await list_services(
    institucion="INTRANT", 
    keyword="licencia", 
    limit=3
)
```

### Manejo de errores

* **Sin resultados**: Retorna `{"results": [], "count": 0}`
* **Error de base de datos**: Retorna mensaje de error estándar
* **Parámetros inválidos**: Retorna error de validación

***

## 2. get\_service\_overview

Obtiene la información principal de un servicio específico.

### Firma

```python
async def get_service_overview(service_id: str) -> str
```

### Parámetros

| Parámetro    | Tipo  | Descripción           | Ejemplo |
| ------------ | ----- | --------------------- | ------- |
| `service_id` | `str` | ID único del servicio | `"163"` |

### Valor de retorno

JSON string con información general del servicio:

```json
{
  "service_id": "163",
  "nombre_servicio": "Renovación Licencia de Conducir",
  "institucion": "INTRANT",
  "contenido": "Servicio: Renovación Licencia de Conducir\nInstitución: INTRANT\nDescripción: Es la renovación de licencias de conducir vencidas...",
  "nombres_alternativos": ["Renovación de Licencia", "Licencia de Conducir"],
  "tipos_disponibles": ["servicio_principal", "variacion_servicio", "ubicaciones"],
  "placeholder": false
}
```

### Ejemplos de uso

```python
# Obtener información general
overview = await get_service_overview("163")

# Para servicio placeholder
overview = await get_service_overview("999")
# Retorna: {"placeholder": true, "message": "Este servicio no tiene información disponible..."}
```

### Manejo de errores

* **Servicio no encontrado**: Retorna placeholder con mensaje de error
* **ID inválido**: Retorna error de validación
* **Base de datos no disponible**: Retorna mensaje de error estándar

***

## 3. list\_service\_variations

Lista las variaciones específicas de un servicio con requisitos y costos.

### Firma

```python
async def list_service_variations(
    service_id: str,
    categoria: Optional[str] = None,
    limit: int = 10,
) -> str
```

### Parámetros

| Parámetro    | Tipo            | Descripción                                | Ejemplo          |
| ------------ | --------------- | ------------------------------------------ | ---------------- |
| `service_id` | `str`           | ID único del servicio                      | `"163"`          |
| `categoria`  | `Optional[str]` | Filtrar por categoría específica           | `"Categoría 01"` |
| `limit`      | `int`           | Número máximo de variaciones (default: 10) | `5`              |

### Valor de retorno

JSON string con variaciones del servicio:

```json
{
  "service_id": "163",
  "variaciones": [
    {
      "categoria": "Renovación Licencia Categoría 01",
      "precio": 1900.0,
      "precio_texto": "mil novecientos pesos dominicanos",
      "concepto_de_pago": "Licencia de Conducir Categoría 01",
      "desglose_de_costos": "• RD$ 1,900 Renovación de Licencia • RD$ 100 Certificación Médica",
      "contenido": "Procedimiento:\n1. Presentarse en oficinas autorizadas\n2. Pasar por Registro\n3. Realizar Evaluación Médica",
      "placeholder": false
    }
  ],
  "count": 1
}
```

### Ejemplos de uso

```python
# Todas las variaciones
variations = await list_service_variations("163")

# Filtrar por categoría
variations = await list_service_variations("163", categoria="Categoría 01")

# Limitar resultados
variations = await list_service_variations("163", limit=5)
```

### Manejo de errores

* **Sin variaciones**: Retorna `{"variaciones": [], "count": 0}`
* **Servicio no encontrado**: Retorna placeholder
* **Categoría no encontrada**: Retorna lista vacía

***

## 4. get\_service\_locations

Obtiene direcciones y horarios de oficinas.

### Firma

```python
async def get_service_locations(
    service_id: str,
    provincia: Optional[str] = None,
    municipio: Optional[str] = None,
    limit: int = 5,
) -> str
```

### Parámetros

| Parámetro    | Tipo            | Descripción                               | Ejemplo               |
| ------------ | --------------- | ----------------------------------------- | --------------------- |
| `service_id` | `str`           | ID único del servicio                     | `"163"`               |
| `provincia`  | `Optional[str]` | Filtrar por provincia                     | `"Santo Domingo"`     |
| `municipio`  | `Optional[str]` | Filtrar por municipio                     | `"Distrito Nacional"` |
| `limit`      | `int`           | Número máximo de ubicaciones (default: 5) | `10`                  |

### Valor de retorno

JSON string con ubicaciones del servicio:

```json
{
  "service_id": "163",
  "ubicaciones": [
    {
      "nombre": "Licencias de Conducir Sede Principal",
      "direccion": "Av. Tiradentes esq. Héctor Homero Hernandez Vargas #7",
      "ubicacion": "Santo Domingo de Guzmán, Distrito Nacional",
      "horario": "08:00:00 - 16:00:00",
      "edificio": "Licencias de Conducir, 1er Nivel"
    }
  ],
  "count": 1
}
```

### Ejemplos de uso

```python
# Todas las ubicaciones
locations = await get_service_locations("163")

# Filtrar por provincia
locations = await get_service_locations("163", provincia="Santo Domingo")

# Filtrar por municipio
locations = await get_service_locations("163", municipio="Distrito Nacional")

# Combinar filtros
locations = await get_service_locations(
    "163", 
    provincia="Santo Domingo", 
    municipio="Distrito Nacional",
    limit=3
)
```

### Manejo de errores

* **Sin ubicaciones**: Retorna `{"ubicaciones": [], "count": 0}`
* **Filtros sin resultados**: Retorna lista vacía
* **Servicio no encontrado**: Retorna placeholder

***

## 5. get\_service\_digital\_channel

Obtiene información sobre disponibilidad online y enlaces.

### Firma

```python
async def get_service_digital_channel(service_id: str) -> str
```

### Parámetros

| Parámetro    | Tipo  | Descripción           | Ejemplo |
| ------------ | ----- | --------------------- | ------- |
| `service_id` | `str` | ID único del servicio | `"163"` |

### Valor de retorno

JSON string con información del canal digital:

```json
{
  "service_id": "163",
  "canal": "Portal WEB INTRANT",
  "enlace": "https://intrant.gob.do/servicios/licencias",
  "enlace_lectura": "intrant punto gob punto do diagonal servicios diagonal licencias",
  "placeholder": false
}
```

### Ejemplos de uso

```python
# Obtener canal digital
digital = await get_service_digital_channel("163")

# Para servicio sin canal digital
digital = await get_service_digital_channel("999")
# Retorna: {"placeholder": true, "message": "No hay canal digital disponible..."}
```

### Manejo de errores

* **Sin canal digital**: Retorna placeholder con mensaje informativo
* **Servicio no encontrado**: Retorna placeholder
* **Enlace inválido**: Retorna canal con enlace vacío

***

## 6. get\_service\_contact

Obtiene teléfonos, correos y portales oficiales.

### Firma

```python
async def get_service_contact(service_id: str) -> str
```

### Parámetros

| Parámetro    | Tipo  | Descripción           | Ejemplo |
| ------------ | ----- | --------------------- | ------- |
| `service_id` | `str` | ID único del servicio | `"163"` |

### Valor de retorno

JSON string con información de contacto:

```json
{
  "service_id": "163",
  "portal": "https://www.intrant.gob.do",
  "telefonos": ["8093386134"],
  "telefonos_lectura": ["8 0 9 3 3 8 6 1 3 4"],
  "correos": ["info@intrant.gob.do"],
  "institucion_contacto": "INTRANT",
  "placeholder": false
}
```

### Ejemplos de uso

```python
# Obtener información de contacto
contact = await get_service_contact("163")

# Para servicio sin información de contacto
contact = await get_service_contact("999")
# Retorna: {"placeholder": true, "message": "No hay información de contacto disponible..."}
```

### Manejo de errores

* **Sin información de contacto**: Retorna placeholder con mensaje informativo
* **Servicio no encontrado**: Retorna placeholder
* **Datos incompletos**: Retorna campos disponibles con campos faltantes como arrays vacíos

***

## 7. ask\_knowledge\_base

Búsqueda semántica en toda la base de conocimiento.

### Firma

```python
async def ask_knowledge_base(query: str) -> str
```

### Parámetros

| Parámetro | Tipo  | Descripción                    | Ejemplo                                                |
| --------- | ----- | ------------------------------ | ------------------------------------------------------ |
| `query`   | `str` | Consulta de búsqueda semántica | `"¿Qué documentos necesito para renovar mi licencia?"` |

### Valor de retorno

String con respuesta basada en la base de conocimiento:

```
Para renovar tu licencia de conducir necesitas los siguientes documentos:

• Cédula de Identidad y Electoral
• Licencia de Conducir actual (si aplica)
• Certificado médico (si es requerido)

El procedimiento incluye:
1. Presentarse en oficinas autorizadas
2. Pasar por Registro
3. Realizar Evaluación Médica

El costo es de mil novecientos pesos dominicanos para la categoría 01.
```

### Ejemplos de uso

```python
# Búsqueda general
result = await ask_knowledge_base("licencia de conducir")

# Pregunta específica
result = await ask_knowledge_base("¿Cuánto cuesta renovar una licencia?")

# Búsqueda por institución
result = await ask_knowledge_base("servicios de INTRANT")

# Consulta sobre requisitos
result = await ask_knowledge_base("¿Qué documentos necesito para pasaporte?")
```

### Manejo de errores

* **Sin resultados**: Retorna mensaje informativo sobre falta de información
* **Base de datos no disponible**: Retorna mensaje de error estándar
* **Consulta vacía**: Retorna mensaje pidiendo más detalles

***

## 8. get\_current\_date

Obtiene la fecha actual en formato legible.

### Firma

```python
async def get_current_date() -> str
```

### Parámetros

Ninguno.

### Valor de retorno

String con la fecha actual en formato legible:

```
Hoy es 15 de enero de 2025
```

### Ejemplos de uso

```python
# Obtener fecha actual
date = await get_current_date()
# Retorna: "Hoy es 15 de enero de 2025"
```

### Manejo de errores

* **Error de sistema**: Retorna fecha por defecto
* **Zona horaria**: Usa zona horaria del servidor

***

## Patrones de uso

### Flujo de conversación típico

```python
# 1. Usuario pregunta sobre un servicio
# 2. Buscar servicios relevantes
services = await list_services(keyword="licencia conducir")

# 3. Obtener información general
overview = await get_service_overview("163")

# 4. Obtener detalles específicos
variations = await list_service_variations("163")
locations = await get_service_locations("163")
contact = await get_service_contact("163")

# 5. Responder con información completa
```

### Búsqueda semántica

```python
# Para consultas complejas o específicas
result = await ask_knowledge_base("¿Qué documentos necesito para renovar mi licencia de conducir categoría 01?")
```

### Validación de servicios

```python
# Verificar si un servicio existe
overview = await get_service_overview("163")
if overview.get("placeholder"):
    # Servicio no disponible
    pass
```

## Configuración

### Variables de entorno

```ini
# ChromaDB
CHROMA_COLLECTION_NAME=servicios
CHROMA_DIRECTORY=storage/chroma
RETRIEVER_K=3
RETRIEVER_FETCH_K=9

# Timeouts
STT_TIMEOUT=15
LLM_TIMEOUT=20
TTS_TIMEOUT=25
```

### Configuración de retriever

```python
_RETRIEVER_CONFIG = {
    "chunks": {
        "directory": Path("storage/chroma"),
        "collection": "servicios",
        "retriever_k": 3,
    },
    "qa": {
        "directory": Path("storage/chroma_qa"),
        "collection": "servicios_qa",
        "retriever_k": 3,
    },
}
```

## Próximos pasos

1. **Referencia de Configuración**: [Referencia de configuración](/taina-agente-ia-ogtic/referencias-tecnicas/api/configuration.md)
2. **Catálogo de Herramientas**: [Catálogo de herramientas](https://github.com/public-intelligence/taina_ogtic/blob/master/taina-gitbook-ogtic/taina-asistente-ia/index/scripts/service-catalog.md)
3. **Pipeline de Datos**: [Pipeline de datos](https://github.com/public-intelligence/taina_ogtic/blob/master/taina-gitbook-ogtic/general/development/data-pipeline.md)

## Recursos adicionales

* [ChromaDB Documentation](https://docs.trychroma.com/)
* [LangChain Vector Stores](https://python.langchain.com/docs/modules/data_connection/vectorstores/)
* [LiveKit Agents Tools](https://docs.livekit.io/agents/tools/)

***

¿Necesitas ayuda? Consulta la [guía de solución de problemas](https://github.com/public-intelligence/taina_ogtic/blob/master/taina-gitbook-ogtic/taina-asistente-ia/index/how-to/troubleshoot.md) o la [documentación de configuración](/taina-agente-ia-ogtic/referencias-tecnicas/api/configuration.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/referencias-tecnicas/api/tools.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.