> ## 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.

# Usar artifacts con OpenAI Agents

> Carga documentos e imágenes y úsalos como contexto al ejecutar un agente con runtime OpenAI Agents.

Los artifacts permiten que un agente analice documentos e imágenes sin enviar
URLs de almacenamiento ni contenido en base64.

> [!NOTE]
>
> Solo puedes usar artifacts cuando el agente tiene
> `runtime: "openai-agents"` y `mode: "chat-conversation"`.

## 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.
* Un agente [configurado](https://developers.insuranceboosters.com/agentes/editar-agente.md) con el runtime
  **OpenAI Agents** (`runtime: "openai-agents"`).

## Flujo de uso

**1. Carga los archivos**

Envía uno o más archivos como `multipart/form-data`. Usa `files` como
nombre de campo para cada archivo:

```bash theme={null}
curl -X POST "https://api.insuranceboosters.com/api/v1/agents/{agentId}/artifacts" \
  -H "x-ib-api-key: TU_API_KEY" \
  -F "files=@poliza.pdf" \
  -F "files=@foto-siniestro.jpg"
```

**2. Guarda los identificadores**

La respuesta contiene una referencia opaca por archivo:

```json theme={null}
{
  "artifacts": [
    {
      "id": "<artifactId>",
      "agentId": "<agentId>",
      "fileName": "poliza.pdf",
      "mimeType": "application/pdf",
      "size": 12345,
      "kind": "document",
      "createdAt": 1710000000000,
      "expiresAt": 1710086400000
    }
  ]
}
```

Conserva `id` y revisa `expiresAt`. La referencia expira 24 horas después
de la carga.

**3. Referencia los artifacts al ejecutar el agente**

Envía los identificadores en `artifacts` al llamar a
`POST /agents/{agentId}/execute`:

```bash theme={null}
curl -X POST "https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute" \
  -H "Content-Type: application/json" \
  -H "x-ib-api-key: TU_API_KEY" \
  -H "x-agent-session-id: mi-sesion-123" \
  -d '{
    "history": [
      {
        "role": "user",
        "content": "Resume las coberturas de la póliza y describe los daños de la fotografía."
      }
    ],
    "artifacts": [
      {"id": "<artifactId-poliza>"},
      {"id": "<artifactId-foto>"}
    ]
  }'
```

## Formatos admitidos

| Categoría | Formatos |
| - | - |
| Documentos | PDF, JSON, TXT, CSV, Markdown, Word (`.doc`, `.docx`) y Excel (`.xls`, `.xlsx`) |
| Imágenes | JPEG, PNG y WebP |

El tipo MIME del archivo debe coincidir con uno de los formatos admitidos.

## Límites y vigencia

| Límite | Valor |
| - | - |
| Archivos por carga | 10 |
| Tamaño por archivo | 25 MB |
| Artifacts por ejecución | 10 |
| Tamaño total por ejecución | 50 MB |
| Vigencia de cada referencia | 24 horas |

Puedes reutilizar una referencia durante su vigencia, siempre que ejecutes el
mismo agente desde la misma cuenta. No puedes usar un artifact de otro agente
ni repetir el mismo `id` dentro de una ejecución.

> [!WARNING]
>
> No envíes una URL, el contenido del archivo en base64 ni los demás campos de
> la respuesta de carga. Cada elemento de `artifacts` debe contener únicamente
> `id`.

## Errores frecuentes

| HTTP | Qué significa | Qué hacer |
| - | - | - |
| `400` | No enviaste archivos, el formato no está admitido o superaste la cantidad permitida. | Usa el campo `files`, revisa el formato y carga hasta 10 archivos. |
| `400` al ejecutar | El artifact expiró, no pertenece al agente, está repetido, supera el total de 50 MB o el runtime no admite archivos. | Carga el archivo de nuevo, usa IDs únicos del mismo agente y confirma que el runtime sea `openai-agents`. |
| `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`. |
| `413` | Un archivo supera 25 MB. | Reduce el tamaño o divide el archivo antes de cargarlo. |


## OpenAPI

````yaml openapi/agentes-v1.yaml POST /agents/{agentId}/artifacts
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}/artifacts:
    post:
      tags:
        - Agentes IA
      summary: Cargar archivos para una ejecución
      description: >
        Carga hasta 10 documentos o imágenes y devuelve referencias opacas. Las
        referencias expiran después de 24 horas y solo pueden usarse con el
        mismo agente y cuenta. Cada archivo admite 25 MB; una ejecución admite
        50 MB entre todas sus referencias. Solo los agentes con runtime
        `openai-agents` pueden usar estas referencias durante una ejecución.
      operationId: uploadAgentArtifacts
      parameters:
        - $ref: '#/components/parameters/AgentId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - files
              properties:
                files:
                  type: array
                  maxItems: 10
                  items:
                    type: string
                    format: binary
      responses:
        '201':
          description: Archivos cargados.
          content:
            application/json:
              schema:
                type: object
                required:
                  - artifacts
                properties:
                  artifacts:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentArtifact'
        '400':
          description: Archivo, tipo MIME o cantidad inválida.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: El agente no existe o no pertenece a tu cuenta.
        '413':
          description: Un archivo excede 25 MB.
components:
  parameters:
    AgentId:
      name: agentId
      in: path
      required: true
      description: Identificador del agente. Solicítalo con tu ejecutivo de cuenta.
      schema:
        type: string
  schemas:
    AgentArtifact:
      type: object
      required:
        - id
        - agentId
        - fileName
        - mimeType
        - size
        - kind
        - createdAt
        - expiresAt
      properties:
        id:
          type: string
        agentId:
          type: string
        fileName:
          type: string
        mimeType:
          type: string
        size:
          type: integer
        kind:
          type: string
          enum:
            - document
            - image
            - text
        createdAt:
          type: number
        expiresAt:
          type: number
    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.
  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.
  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.