Niucore

Referencia

Agentes

Definiciones de agentes y el detalle de las tareas que corrió un turno.

Listar agentes

GETapi.niucore.com/api/v1/agents

Scope: agents:read

Agentes visibles para la credencial, ordenados por nombre. Incluye los propios inactivos, para que su dueño los vea; esos no se pueden adjuntar a un turno.

Nota

agents:read no habilita delegar y agents:use no habilita leer definiciones: son dos scopes estrictos. Para saber qué agentes puede usar un turno, mirá el bloque agents de `GET /chat/catalog`.

Consulta

pageintegerpor defecto 1

Página, empezando en 1.

sizeintegerpor defecto 50

Elementos por página. Máximo 200.

Devuelve

idinteger

Identificador.

namestring

Nombre.

descriptionstring | null

Para qué sirve.

tagstring | null

Dominio de trabajo (finanzas, soporte…).

levelstring

Alcance del agente.

visibilitystring

private, shared o public.

is_activeboolean

Un agente inactivo propio aparece en la lectura pero no se puede adjuntar a un turno ni está en el catálogo del chat.

is_anchoredboolean

Obligatorio para la empresa.

versioninteger

Versión de la definición.

model_idinteger | null

Modelo fijo de sus tareas. null = hereda el del turno. Como conductor (principal_agent_id) usa siempre el modelo del turno.

created_atstring (date-time)

Creación.

updated_atstring (date-time)

Última edición.

Errores

  • 503api_v1_agents_disabledLos agentes están deshabilitados temporalmente en la API (meta.error_details.retry_action: "none"). El historial y el detalle de tareas siguen disponibles.
curl -sS -X GET 'https://api.niucore.com/api/v1/agents' \
  -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN"
Respuesta
{
  "status": "success",
  "message": "Operación exitosa",
  "message_code": "api_v1_ok",
  "data": [
    {
      "id": 4,
      "name": "Contador",
      "description": "Cierra el mes y revisa asientos.",
      "tag": "finanzas",
      "level": "user",
      "visibility": "private",
      "is_active": true,
      "is_anchored": false,
      "version": 3,
      "model_id": null,
      "created_at": "2026-09-19T21:50:10Z",
      "updated_at": "2026-09-23T10:02:44Z"
    }
  ],
  "meta": {
    "request_id": "9f1c0a3e-7b2d-4f18-9a55-2c6e0d1b4a77",
    "page": 1,
    "size": 50,
    "total": 1
  }
}

Ver un agente

GETapi.niucore.com/api/v1/agents/{agent_id}

Scope: agents:read

Detalle de una definición, con instructions y persona.

Ruta

agent_idintegerobligatorio

Identificador.

Devuelve

idinteger

Identificador.

namestring

Nombre.

descriptionstring | null

Para qué sirve.

tagstring | null

Dominio de trabajo (finanzas, soporte…).

levelstring

Alcance del agente.

visibilitystring

private, shared o public.

is_activeboolean

Un agente inactivo propio aparece en la lectura pero no se puede adjuntar a un turno ni está en el catálogo del chat.

is_anchoredboolean

Obligatorio para la empresa.

versioninteger

Versión de la definición.

model_idinteger | null

Modelo fijo de sus tareas. null = hereda el del turno. Como conductor (principal_agent_id) usa siempre el modelo del turno.

instructionsstring

Solo en el detalle. Forma canónica, con las citas {{tipo:id}} tal cual: leer la definición no autoriza cargar lo que cita.

personaobject

Solo en el detalle. Rasgos de tono.

created_atstring (date-time)

Creación.

updated_atstring (date-time)

Última edición.

Errores

  • 404api_v1_not_foundNo existe, o está fuera del alcance de la credencial. Los dos casos responden igual.
  • 503api_v1_agents_disabledLos agentes están deshabilitados temporalmente en la API (meta.error_details.retry_action: "none"). El historial y el detalle de tareas siguen disponibles.
curl -sS -X GET 'https://api.niucore.com/api/v1/agents/4' \
  -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN"
Respuesta
{
  "status": "success",
  "message": "Operación exitosa",
  "message_code": "api_v1_ok",
  "data": {
    "id": 4,
    "name": "Contador",
    "description": "Cierra el mes y revisa asientos.",
    "tag": "finanzas",
    "level": "user",
    "visibility": "private",
    "is_active": true,
    "is_anchored": false,
    "version": 3,
    "model_id": null,
    "created_at": "2026-09-19T21:50:10Z",
    "updated_at": "2026-09-23T10:02:44Z",
    "instructions": "Sos el contador de la empresa. Buscá en {{workspace:31}} antes de responder.",
    "persona": {
      "tone": "formal",
      "verbosity": "brief",
      "language": "es"
    }
  },
  "meta": {
    "request_id": "9f1c0a3e-7b2d-4f18-9a55-2c6e0d1b4a77"
  }
}

Tareas de agentes de un mensaje

GETapi.niucore.com/api/v1/chats/{chat_id}/messages/{message_id}/agent-runs

Scope: chat:read

Estado durable de las tareas que corrió un turno: resumen más encargo, pasos, mensajes entre tareas y resultado. Incluye temporales, fallidas y canceladas, y sobrevive a que el agente se borre después.

Es historial de esta credencial: pide chat:read, y agents:read no da acceso a chats ajenos. Otra credencial del mismo usuario, otro chat, otro mensaje o un chat borrado responden 404.

Nota

Recupera lo que quedó escrito, no reproduce el stream. Los pasos no traen argumentos ni resultados de herramientas; el encargo, las listas y el resultado están acotados, y truncated: true avisa cuando se recortó algo.

Ruta

chat_idstring (uuid)obligatorio

Chat.

message_idintegerobligatorio

Mensaje (turno).

Consulta

pageintegerpor defecto 1

Página, empezando en 1.

sizeintegerpor defecto 50

Elementos por página. Máximo 200.

Devuelve

task_idstring

Correlación opaca de la tarea dentro del mensaje. Es el mismo en message.step, message.action_required, el terminal y el historial. No autoriza nada: una aprobación se resuelve con su action_id.

agent_idinteger | null

null para un agente temporal.

namestring

Nombre al ejecutar.

kindstring

user o temporal.

tagstring | null

Etiqueta.

statestring

submitted, working, waiting, input_required, paused, completed, failed o cancelled.

reasonstring | null

Motivo de un terminal pedido desde afuera.

modelstring | null

Modelo efectivo.

providerstring | null

Proveedor efectivo.

model_requestedstring | null

Modelo fijo que pedía la definición.

fallback_reasonstring | null

Por qué no se usó el modelo pedido.

operation_outcomestring | null

not_dispatched, applied o unknown. `unknown` no es reintento seguro, aunque el turno se haya cancelado.

retry_safeboolean | null

Si repetir la tarea es seguro.

tokensobject

input_tokens, output_tokens, total_tokens de la tarea. Ya están incluidos en usage.total_tokens del turno.

started_atstring | null

Inicio.

finished_atstring | null

Fin.

updated_atstring | null

Última escritura.

briefobject | null

Encargo: objective, output_format, tools_guidance, boundaries, inputs, label.

stepsarray

{ title, status, detail?, tools? }.

messagesarray

Mensajes entre tareas: { from_name, state, content, created_at }. Son datos, no instrucciones del usuario.

resultstring | null

Resultado de la tarea.

truncatedboolean

Algo se recortó.

Errores

  • 404api_v1_not_foundNo existe, o está fuera del alcance de la credencial. Los dos casos responden igual.
curl -sS -X GET 'https://api.niucore.com/api/v1/chats/3f6b1a90-6c2d-4d84-a0b1-9d0f5e7c2ab3/messages/90214/agent-runs' \
  -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN"
Respuesta
{
  "status": "success",
  "message": "Operación exitosa",
  "message_code": "api_v1_ok",
  "data": [
    {
      "task_id": "task_6f0d2a9b41c8e7735a10bd42",
      "agent_id": 4,
      "name": "Contador",
      "kind": "user",
      "tag": "finanzas",
      "state": "completed",
      "reason": null,
      "model": "gpt-4o",
      "provider": "openai",
      "model_requested": null,
      "fallback_reason": null,
      "operation_outcome": "applied",
      "retry_safe": null,
      "tokens": {
        "input_tokens": 1840,
        "output_tokens": 312,
        "total_tokens": 2152
      },
      "started_at": "2026-09-25T10:00:01Z",
      "finished_at": "2026-09-25T10:00:19Z",
      "updated_at": "2026-09-25T10:00:19Z",
      "brief": {
        "objective": "Conciliar los asientos de agosto.",
        "output_format": "Tabla con diferencias."
      },
      "steps": [
        {
          "title": "Buscando en tus bibliotecas",
          "status": "completed",
          "tools": [
            "search_documents"
          ]
        }
      ],
      "messages": [],
      "result": "Hay dos asientos sin contrapartida: 4471 y 4502.",
      "truncated": false
    }
  ],
  "meta": {
    "request_id": "9f1c0a3e-7b2d-4f18-9a55-2c6e0d1b4a77",
    "page": 1,
    "size": 50,
    "total": 1
  }
}