Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gcapella0/agente-inteligente-expedientes/llms.txt

Use this file to discover all available pages before exploring further.

The Agents API lets you monitor and control the four processing agents that form the document ingestion pipeline: watcher, ocr, classifier, and storage. Each agent can be triggered independently or as part of a sequential pipeline where each step feeds the next.

​
GET /agentes

List the current state of every agent and the overall pipeline status. Authentication: Authorization: Bearer <token> required.

​
Response 200 OK

{
  "agentes": [
    {
      "nombre": "watcher",
      "estado": "idle",
      "ultimo_run": "2024-01-15T10:30:00Z",
      "total_procesados": 42,
      "error_msg": null,
      "siguiente_en_pipeline": "ocr"
    },
    {
      "nombre": "ocr",
      "estado": "idle",
      "ultimo_run": "2024-01-15T10:31:05Z",
      "total_procesados": 40,
      "error_msg": null,
      "siguiente_en_pipeline": "classifier"
    },
    {
      "nombre": "classifier",
      "estado": "error",
      "ultimo_run": "2024-01-14T08:00:00Z",
      "total_procesados": 38,
      "error_msg": "LLM timeout after 120s",
      "siguiente_en_pipeline": "storage"
    },
    {
      "nombre": "storage",
      "estado": "idle",
      "ultimo_run": "2024-01-14T08:05:00Z",
      "total_procesados": 35,
      "error_msg": null,
      "siguiente_en_pipeline": null
    }
  ],
  "pipeline_activo": false,
  "pipeline_paso_actual": null
}

​
Response fields

​
agentes
array
One entry per agent in pipeline order.
​
agentes[].nombre
string
Agent identifier. One of watcher | ocr | classifier | storage.
​
agentes[].estado
string
Current agent state: idle | running | error.
​
agentes[].ultimo_run
string | null
ISO 8601 UTC timestamp of the last completed run, or null if never run.
​
agentes[].total_procesados
integer
Cumulative count of successful executions since the last state reset.
​
agentes[].error_msg
string | null
Last error message if estado is error, otherwise null.
​
agentes[].siguiente_en_pipeline
string | null
Name of the next agent in the chain. null for storage (last step).
​
pipeline_activo
boolean
true while a pipeline execution is in progress.
​
pipeline_paso_actual
string | null
Name of the agent currently executing inside the pipeline, or null when idle.
Agent state is persisted in the MongoDB collection sistema_agentes_estado. On API startup, any agents stuck in running state are automatically reset to idle to prevent stale locks after a crash or restart.

​
POST /agentes/{nombre}/ejecutar

Trigger execution of a single agent or start the full pipeline from that agent onward. Authentication: Authorization: Bearer <token> required.

​
Path parameters

​
nombre
string
required
The agent to execute. Must be one of: watcher, ocr, classifier, storage.

​
Query parameters

​
modo
string
default:"independiente"
Execution mode:
  • independiente — runs only the specified agent, no chain.
  • pipeline — runs the specified agent and all subsequent agents in order (watcher → ocr → classifier → storage).

​
Response 202 Accepted

Execution is started as a FastAPI BackgroundTask and the response is returned immediately. 
{
  "mensaje": "Ejecución iniciada",
  "agente": "watcher",
  "modo": "pipeline",
  "id_ejecucion": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "siguiente_agente": "ocr"
}
​
id_ejecucion
string
Unique hex identifier for this execution run. Useful for correlating log entries.
​
siguiente_agente
string | null
Next agent that will run after this one when modo=pipeline. null when running in independiente mode or when the last agent in the chain is triggered.

​
Error responses

StatusCondition
400 Bad Requestnombre is not a valid agent name, or modo is not independiente / pipeline.
409 ConflictThe specified agent is already in running state, or (when modo=pipeline) another pipeline execution is already active.
500 Internal Server ErrorUnexpected error starting the background task.
BackgroundTasks are not cancelable mid-execution. Calling POST /agentes/{nombre}/stop sets the agent’s state to idle and clears the pipeline flag, which prevents the pipeline from advancing to the next step, but it will not abort a step that is already running in the thread pool.

​
POST /agentes/{nombre}/stop

Mark an agent as stopped and deactivate the pipeline flag. Authentication: Authorization: Bearer <token> required.

​
Path parameters

​
nombre
string
required
The agent to stop. Must be one of: watcher, ocr, classifier, storage.

​
Response 200 OK

{
  "exito": true,
  "agente": "watcher",
  "estado": "detenido"
}
This endpoint:
  1. Sets estado → idle in MongoDB for the given agent.
  2. Sets error_msg → "Detenido por el usuario".
  3. Sets pipeline_activo → false and pipeline_paso_actual → null.
  4. Writes a stop_agente audit event via audit_log().

​
cURL examples

# List all agents and pipeline status
curl http://localhost:8000/agentes \
  -H "Authorization: Bearer $TOKEN"

# Start the full pipeline from the beginning (watcher → ocr → classifier → storage)
curl -X POST "http://localhost:8000/agentes/watcher/ejecutar?modo=pipeline" \
  -H "Authorization: Bearer $TOKEN"

# Run the OCR agent independently (no chain)
curl -X POST "http://localhost:8000/agentes/ocr/ejecutar?modo=independiente" \
  -H "Authorization: Bearer $TOKEN"

# Stop the pipeline (prevents advancing to the next step)
curl -X POST "http://localhost:8000/agentes/watcher/stop" \
  -H "Authorization: Bearer $TOKEN"

​
Pipeline execution model

The four agents run in a fixed order: 
watcher  →  ocr  →  classifier  →  storage
When modo=pipeline the background thread checks the pipeline_activo flag in MongoDB before starting each step. If the flag was cleared by a stop call, execution halts without running the remaining agents. A 2-second pause is inserted between steps to allow state to propagate. Each agent function is resolved lazily from src.main at runtime, so any changes to agent logic take effect on the next invocation without restarting the API.

Build docs developers (and LLMs) love

Get started for freeTalk to us