Archivos y artefactos

Archivos

const file = await client.uploadFile({
  filename: 'recibo.pdf',
  contentType: 'application/pdf',
  contentBase64: await toBase64(blob),
  metadata: { source: 'checkout-upload' },
});

const { files } = await client.listFiles();
const fetched = await client.getFile(file.fileRef);

Las subidas van en base64 en el cuerpo de la petición: no hay un flujo aparte multipart ni con URL firmada. Consulta antes policy.filePolicy, que contiene upload, read, maxUploadBytes y allowedMimeTypes, todos aplicados en el servidor.

const { filePolicy } = await client.getEffectivePolicy();

if (!filePolicy.upload || !filePolicy.allowedMimeTypes.includes(blob.type)) {
  return refuseUpload();
}
if (blob.size > filePolicy.maxUploadBytes) {
  return refuseUpload();
}

Cada archivo vuelve como un RuntimeFile — fileRef, name y, opcionalmente, mimeType, sizeBytes, status, createdAt y metadata. Conviene ramificar según status: un archivo recién subido puede estar en processing antes de pasar a available.

Pasa los valores fileRef a streamMessage({ fileRefs }) para referenciarlos en un turno — ver Conversaciones y streaming.

Las operaciones sobre la biblioteca de contexto necesitan un espacio de trabajo

Las operaciones de archivos que tocan la biblioteca de contexto del agente requieren un binding materializado con ensureWorkspace() y soporte en la política. Ver Espacios de trabajo.

Artefactos

Los artefactos son salidas duraderas que produce un agente: un documento, una tabla, un archivo generado. Llegan como eventos artifact:created a mitad del stream, y en message:complete dentro del array artifacts. Lee uno por su ref:

const policy = await client.getEffectivePolicy();

if (policy.capabilities.artifacts) {
  const artifact = await client.getArtifact('artifact_public_12345678');

  console.log(
    artifact.title,
    artifact.status,
    artifact.contentType,
    artifact.contentText ?? artifact.contentJson,
  );
}

GetArtifactResult devuelve solo campos seguros para el público: artifactRef, kind, title, status, contentType, contentText, contentJson, summaryText, renderHints y createdAt. Sin IDs internos y sin ubicaciones de almacenamiento.

renderHints son metadatos de presentación orientativos; trátalos como una sugerencia, no como un contrato, y ten siempre un renderizado de reserva.

Comportamiento ante errores

Situación	Resultado
capabilities.artifacts está desactivado	403 con un error estable unsupported_capability del SDK
Ref fuera del límite de aislamiento de la sesión o el espacio de trabajo actual	404

Ambos son estables: el 404 es deliberado, para que una ref de otro inquilino sea indistinguible de una que no existe.