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

# Editar agente personalizado

> Actualiza uno o más campos de un agente de IA administrado desde la plataforma.

Actualiza uno o más campos de un agente personalizado. Los campos que no envíes conservan su valor actual.

Antes de empezar, necesitas:

* Una [API key](https://developers.insuranceboosters.com/autenticacion.md).
* El `agentId`, disponible en la URL del agente dentro de la plataforma.

## Actualizar el agente

Llama a `PUT /agents/{agentId}` con los campos que quieres cambiar. Sustituye `{agentId}` y `TU_API_KEY`:

```bash theme={null}
curl -X PUT "https://api.insuranceboosters.com/api/v1/agents/{agentId}" \
  -H "Content-Type: application/json" \
  -H "x-ib-api-key: TU_API_KEY" \
  -d '{
    "name": "Asistente de Acme Seguros",
    "instructions": "<instrucciones>",
    "isActive": true
  }'
```

Si incluyes `modelConfig`, `toolIds` o `topicIds`, ese valor reemplaza por completo al anterior. Un arreglo vacío en `toolIds` o `topicIds` quita la lista.

## Campos

| Campo | Tipo | Descripción |
| - | - | - |
| `name` | `string` | Nombre del agente. Si lo envías, no puede ir vacío. |
| `description` | `string` | Descripción del agente. |
| `instructions` | `string` | Instrucciones que definen su comportamiento. |
| `modelConfig` | `object` | Proveedor, modelo y temperatura. Reemplaza la configuración completa. |
| `toolIds` | `string[]` | Identificadores de herramientas. Reemplaza la lista completa. |
| `topicIds` | `string[]` | Identificadores de temas. Reemplaza la lista completa. |
| `isActive` | `boolean` | `true` permite ejecutar el agente. `false` hace que la ejecución responda `400`. |
| `version` | `integer` | Entero positivo. Si lo envías, reemplaza la versión guardada. |

### `modelConfig`

`provider` y `model` son obligatorios cuando envías este objeto. `temperature` es opcional.

| Campo | Tipo | Descripción |
| - | - | - |
| `provider` | `string` | `openai` o `gemini`. |
| `model` | `string` | Identificador del modelo. |
| `temperature` | `number` | Valor entre `0` y `2`. |

## Respuesta

Un `200` devuelve el agente actualizado.

| Campo | Tipo | Descripción |
| - | - | - |
| `id` | `string` | Identificador del agente. |
| `tenantId` | `string` | Identificador de tu cuenta. |
| `name` | `string` | Nombre del agente. |
| `description` | `string` | Descripción, si existe. |
| `instructions` | `string` | Instrucciones, si existen. |
| `modelConfig` | `object` | Configuración del modelo, si existe. |
| `toolIds` | `string[]` | Herramientas asociadas, si existen. |
| `topicIds` | `string[]` | Temas asociados, si existen. |
| `isActive` | `boolean` | Estado de ejecución, si está definido. |
| `version` | `integer` | Versión del agente. |
| `createdAt` | `number` | Creación en milisegundos (epoch). |
| `lastUpdatedAt` | `number` | Última actualización en milisegundos (epoch). |

```json theme={null}
{
  "id": "<agentId>",
  "tenantId": "<tenantId>",
  "name": "Asistente de Acme Seguros",
  "description": "Atiende consultas de pólizas.",
  "instructions": "<instrucciones>",
  "modelConfig": {
    "provider": "openai",
    "model": "<modelo>",
    "temperature": 0.2
  },
  "toolIds": ["<toolId>"],
  "topicIds": ["<topicId>"],
  "isActive": true,
  "version": 2,
  "createdAt": 1710000000000,
  "lastUpdatedAt": 1710003600000
}
```

## Errores frecuentes

| HTTP | Qué significa | Qué hacer |
| - | - | - |
| `400` | El body no cumple el esquema, o una herramienta o un tema no es válido. | Revisa tipos, `provider`, `temperature` (0 a 2) y que cada id de `toolIds` y `topicIds` pertenezca a tu cuenta. |
| `401` | API key inválida o faltante. | Verifica `x-ib-api-key`. |
| `404` | El agente no existe o no pertenece a tu cuenta. | Abre el agente en la plataforma y confirma su `agentId`. |
| `500` | Error inesperado. | Reintenta; si continúa, contacta soporte. |


## OpenAPI

````yaml openapi/agentes-v1.yaml PUT /agents/{agentId}
openapi: 3.1.0
info:
  title: Insurance Boosters API — Agentes IA
  version: 1.0.0
  description: >-
    API pública para actualizar un agente de IA de tu cuenta y enviarle un
    mensaje.
  license:
    name: Propietaria
    url: https://insuranceboosters.com
servers:
  - url: https://api.insuranceboosters.com/api/v1
    description: Producción
security:
  - IbApiKey: []
tags:
  - name: Agentes IA
    description: Edición y ejecución de agentes de IA.
paths:
  /agents/{agentId}:
    put:
      tags:
        - Agentes IA
      summary: Editar agente
      description: >
        Actualiza un agente de IA. Envía solo los campos que quieres cambiar;
        los demás conservan su valor. Si incluyes `modelConfig`, `toolIds` o
        `topicIds`, ese valor reemplaza por completo al anterior.
      operationId: updateAgent
      parameters:
        - $ref: '#/components/parameters/AgentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentRequest'
            example:
              name: Asistente de Acme Seguros
              instructions: Responde consultas con información clara y breve.
              isActive: true
      responses:
        '200':
          description: Agente actualizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
              example:
                id: <agentId>
                tenantId: <tenantId>
                name: Asistente de Acme Seguros
                description: Atiende consultas de pólizas.
                instructions: Responde consultas con información clara y breve.
                modelConfig:
                  provider: openai
                  model: <modelo>
                  temperature: 0.2
                toolIds:
                  - <toolId>
                topicIds:
                  - <topicId>
                isActive: true
                version: 2
                createdAt: 1710000000000
                lastUpdatedAt: 1710003600000
        '400':
          description: >
            El body no cumple el esquema, o un identificador de `toolIds` o
            `topicIds` no es válido para tu cuenta.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                campoInvalido:
                  summary: Nombre vacío
                  value:
                    error:
                      - message: Name is required
                        path:
                          - name
                herramientaInvalida:
                  summary: Herramienta no disponible
                  value:
                    error: >-
                      Una o más herramientas seleccionadas ya no están
                      disponibles. Quítalas de la selección e intenta guardar de
                      nuevo.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: El agente no existe o no pertenece a tu cuenta.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Agent with ID <agentId> not found.
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    AgentId:
      name: agentId
      in: path
      required: true
      description: Identificador del agente. Solicítalo con tu ejecutivo de cuenta.
      schema:
        type: string
  schemas:
    UpdateAgentRequest:
      type: object
      description: >
        Campos a modificar. Todos son opcionales. Los que omites conservan su
        valor actual.
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          description: Nombre del agente. Si lo envías, no puede ir vacío.
        description:
          type: string
          description: Descripción del agente.
        instructions:
          type: string
          description: Instrucciones que definen el comportamiento del agente.
        modelConfig:
          $ref: '#/components/schemas/ModelConfig'
        toolIds:
          type: array
          description: >
            Identificadores de las herramientas del agente. Si lo envías,
            reemplaza la lista completa. Un arreglo vacío las quita.
          items:
            type: string
        topicIds:
          type: array
          description: >
            Identificadores de los temas del agente. Si lo envías, reemplaza la
            lista completa. Un arreglo vacío los quita.
          items:
            type: string
        isActive:
          type: boolean
          description: >
            Indica si el agente acepta ejecuciones. Con `false`, ejecutar el
            agente responde 400.
        version:
          type: integer
          minimum: 1
          description: Versión del agente. Entero positivo.
    Agent:
      type: object
      required:
        - id
        - tenantId
        - name
        - version
        - createdAt
        - lastUpdatedAt
      additionalProperties: true
      properties:
        id:
          type: string
          description: Identificador del agente.
        tenantId:
          type: string
          description: Identificador de tu cuenta.
        name:
          type: string
          minLength: 1
          description: Nombre del agente.
        description:
          type: string
          description: Descripción del agente.
        instructions:
          type: string
          description: Instrucciones del agente.
        modelConfig:
          $ref: '#/components/schemas/ModelConfig'
        toolIds:
          type: array
          items:
            type: string
          description: Identificadores de las herramientas asociadas.
        topicIds:
          type: array
          items:
            type: string
          description: Identificadores de los temas asociados.
        isActive:
          type: boolean
          description: Indica si el agente acepta ejecuciones.
        version:
          type: integer
          minimum: 1
          description: Versión del agente.
        createdAt:
          type: number
          description: Marca de tiempo de creación en milisegundos (epoch).
        lastUpdatedAt:
          type: number
          description: Marca de tiempo de la última actualización en milisegundos (epoch).
    Error:
      type: object
      properties:
        error:
          description: Detalle del error de validación o de negocio.
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                additionalProperties: true
        message:
          type: string
          description: Mensaje de error de autenticación.
    ModelConfig:
      type: object
      required:
        - provider
        - model
      additionalProperties: false
      properties:
        provider:
          type: string
          enum:
            - openai
            - gemini
          description: Proveedor del modelo.
        model:
          type: string
          description: Identificador del modelo.
        temperature:
          type: number
          minimum: 0
          maximum: 2
          description: Control de variación de la respuesta. Valor entre 0 y 2.
  responses:
    Unauthorized:
      description: API key inválida o faltante.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalidApiKey:
              value:
                message: Invalid API key.
            missingAuth:
              value:
                message: Invalid authorization format.
    InternalError:
      description: Error inesperado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Internal server error.
  securitySchemes:
    IbApiKey:
      type: apiKey
      in: header
      name: x-ib-api-key

````

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