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

# Facematch Agent

> System for 1:1 facial comparison between two images to determine if they correspond to the same person

<Info>
  **Version:** 1.3.0-public
</Info>

The **Facematch Agent** is a multi-agent system that employs the "1:1 facial match" technique to determine whether two facial images correspond to the same person, applying a defined tolerance level to ensure result accuracy.

This agent can be used when you need to verify the presence of a face and evaluate its similarity.

## User experience

### ✅ Checklist to start without blockers

* The **inputs** (document photo and video selfie photo) must come from the **Document Check Agent** and the **Liveness Check Agent**.
* Configure the comparison **threshold** (recommended: 60%) and the **provider** (for example Jelou, or others).
* <u>Recommended:</u> define the handling flow if you enable **Human in the loop** (who reviews, response times, and what happens if there is no response).

### Validations

<CardGroup cols={3}>
  <Card title="Face Detection" icon="face-smile">
    We identify the presence and location of faces in the obtained images.
  </Card>

  <Card title="Facial Comparison" icon="user-check">
    We verify whether the detected faces match.
  </Card>

  <Card title="Similarity Level Definition" icon="percentage">
    We calculate the similarity percentage between images to confirm whether they belong to the same person.
  </Card>
</CardGroup>

### Process

The video selfie obtained during the liveness check is compared against two possible sources:

* **Identity Document Photo:** We use the photo extracted from the document, ensuring beforehand that the document is authentic and the information has been verified with government sources, guaranteeing a high identity security standard.
* **Photo Registered with the Government Entity:** When available, we also compare the video selfie with the photo stored in government databases.

## Configuration

<Tabs>
  <Tab title="Inputs">
    <AccordionGroup>
      <Accordion title="% Accepted threshold for facial comparison" icon="percentage">
        <ParamField body="% Accepted threshold for facial comparison" type="string" required>
          Variable: `facematchThreshold`. Minimum threshold required for facematch comparison.

          **Type:** Text (0-100)

          **Recommended:** 60%
        </ParamField>
      </Accordion>

      <Accordion title="Face photo extracted from ID card" icon="id-card">
        <ParamField body="Face photo extracted from ID card" type="string" required>
          Variable: `imgDocumentNumber`. Photo extracted from the ID card.
        </ParamField>
      </Accordion>

      <Accordion title="Video Selfie Photo" icon="video">
        <ParamField body="Video Selfie Photo" type="string" required>
          Variable: `imgVideoSelfie`. Photo extracted from the Video Selfie.
        </ParamField>
      </Accordion>

      <Accordion title="Provider" icon="server">
        <ParamField body="Provider" type="string" required>
          Variable: `provider`. Facematch provider.

          **Available values:** `Jelou`, `Facephi`

          **Recommended:** `Jelou`
        </ParamField>
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Outputs">
    ### ✅ Success

    <AccordionGroup>
      <Accordion title="Facial Verification Successful" icon="circle-check">
        Facial verification has been completed successfully.

        **Variable:** `facematchSuccess`

        <Tip>
          To access the information in this variable use the command `$memory.get("result_facematch")`
        </Tip>

        **Response example:**

        ```json theme={null}
        {
          "result_facematch": {
            "facematch_result": "approved",
            "facematch_confidence": 99
          }
        }
        ```

        **Important fields:**

        * `facematch_result`: Comparison result (example: `approved` or `decline`)
        * `facematch_confidence`: Confidence level in percentage (0-100)
        * `error_name`: Error name if one occurred (empty if no error)

        <Note>
          The `result_facematch` object corresponds to the response from the **Facematch AWS Recognition (TOOL)** tool.
        </Note>

        **Information saved in Memory:**

        The agent automatically saves the following information in [memory variables](/guides/variables/memory):

        ```json theme={null}
        {
          "facematchResult": true,
          "result_facematch": {
            "facematch_result": "approved",
            "facematch_confidence": 99,
            "error_name": ""
          }
        }
        ```

        **Available variables:**

        * `$memory.facematchResult`: Indicates whether facial verification was successful (`true`) or not (`false`)
        * `$memory.result_facematch`: Object with the complete result of the facial comparison (response from the Facematch AWS Recognition tool)

        <Tip>
          You can access this information at any point in the flow using `$memory.get("facematchResult")` or `$memory.get("result_facematch")`.
        </Tip>
      </Accordion>
    </AccordionGroup>

    ### 🔴 Errors

    <AccordionGroup>
      <Accordion title="Facial Verification Unsuccessful" icon="triangle-exclamation">
        Facial verification was not successful.

        **Variable:** `facematchFailedError`
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

## Integration

<Steps>
  <Step title="Select the workflow">
    Go to the Workflow within the company where you need to install this Agent. Click the floating button with the workflow name and the folder icon to open the Workflows & Tools panel. Select "Open Marketplace" and there type the Agent name and download it.
  </Step>

  <Step title="Initial configuration">
    The first thing to configure is the **Version** found under "Advanced settings".

    <Tip>
      **Important:** All fields in this Agent are **Mandatory**. You must enter:

      * The inputs to compare (document photo and video selfie photo)
      * The required threshold (recommended: 60%)
      * The provider (generally should be "Jelou")
    </Tip>
  </Step>

  <Step title="Configure Outputs">
    This Agent has 1 error output and 1 success output. Each can be directed to:

    * A text box with a custom message
    * The PMA (Multiagent Panel) if the client has this module
  </Step>

  <Step title="Run tests">
    With the configuration you just completed, you can proceed to run tests using a workflow or another agent as a precursor. Make sure the inputs come from the **Document Check Agent** and the **Liveness Check Agent**.
  </Step>
</Steps>