# Technical Guide

This guide provides technical documentation for setting up, understanding, and extending the Digital Employee Personnel Admin.

### How to Setup

#### Prerequisites

Before starting, ensure you have:

* **Python 3.11 or 3.12**
* **uv >= 0.6.15** (replaces Poetry)
* **Google Cloud SDK** (for accessing internal package repositories)
* **Access to CATAPA API** with valid credentials

#### Installation Steps

1. **Clone the repository**:

   <pre class="language-bash" data-line-numbers><code class="lang-bash">git clone https://github.com/GDP-ADMIN/digital-employee.git
   cd common/applications/digital-employee-personnel-admin
   </code></pre>
2. **Install dependencies**:

   <pre class="language-bash" data-line-numbers><code class="lang-bash">make install
   </code></pre>

   This command configures Poetry authentication for internal repositories and installs all project dependencies.
3. **Configure environment variables**:

   Copy the example environment file and update with your credentials. See [Environment Variables](#environment-variables) for detailed descriptions.

   <pre class="language-bash" data-line-numbers><code class="lang-bash">cp .env.example .env
   </code></pre>
4. **Run the application locally** (optional, for testing):

   <pre class="language-bash" data-line-numbers><code class="lang-bash"># Run locally with default message
   make run

   # Run with custom message
   make run MESSAGE="Show me employees hired in 2024-2025"
   </code></pre>

#### Deployment

1. **Agent deployment:**\
   Agent deployment is handled by the Digital Employee team through Continuous Delivery (CD). This process registers the Digital Employee—along with its identity, tools, and configurations—on the AIP platform.
2. **Enable the agent in CATAPA Chat admin dashboard**:
   * Log in to the [CATAPA Chat](http://claudia.catapa.com/) admin dashboard
   * Navigate to the [Application settings](https://claudia.catapa.com/admin/chatbot)
   * Create or edit an application
   * Add **DE Personnel Admin** as a supported agent in the application
   * Click **Next** to save the configuration
   * Manage user access to this application
3. **Start using the agent**:

   You can now interact with the DE Personnel Admin via [CATAPA Chat](http://claudia.catapa.com/).<br>

   <figure><img src="https://2914931754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXbRDlxflF58D1QG2tLmP%2Fuploads%2FCQo78KXPEsAnoU7uPe72%2Fimage.png?alt=media&#x26;token=745e25f1-da4e-471d-b6d4-02faddc1ef5f" alt=""><figcaption></figcaption></figure>

### Agent Architecture Diagram

The Digital Employee Payroll Officer uses a single-agent architecture with specialized tools for different tasks.

{% @mermaid/diagram content="flowchart LR

A0\["DE Personnel Admin"]
A1\["DE Quality of Hire Analyst"]

subgraph Tools
T1\["Catapa Employee List"]
T2\["Master Data - Institution"]
T3\["Master Data - Field of Study"]
T4\["Master Data - Education Level"]
T5\["Master Data - Vendor"]
T6\["Employee Education"]
T7\["Employee Job Experience"]
T8\["Employee Termination"]
T9\["Employee Promotion"]
T10\["Employee Salary Changes"]
T11\["Employee KPI"]
end

A0 --> A1

A1 --> T1
A1 --> T2
A1 --> T3
A1 --> T4
A1 --> T5
A1 --> T6
A1 --> T7
A1 --> T8
A1 --> T9
A1 --> T10
A1 --> T11" %}

The architecture follows a hierarchical delegation model where the Coordinator Agent handles high-level orchestration and decision-making, while specialized sub-agents focus on specific operational tasks. The Quality of Hire analyst Agent handle employees performance analysis.

#### **Agent Description**

**Personnel Admin Agent (Coordinator)**

* **Type**: Main Coordinator Agent
* **Purpose**: Orchestrates personnel admin workflows by delegating tasks to specialized sub-agents
* **Model**: Default model (from `digital_employee_core`)
* **Key Capabilities**:
  * Delegates specific operations to specialized sub-agents
* **Tools**:&#x20;
  * `time_tool`
  * `date_range_tool`
* **MCPs**: None
* **Sub-agents**: Quality of Hire Analyst Agent
* **Configurations**: CATAPA credentials (tenant, base\_url, client\_id, client\_secret)

**Quality of Hire Analyst Agent**

* **Type**: Specialized Sub-Agent
* **Purpose**: Analyze employee performance based on predefined metrics and return insight.
* **Model**: GPT-5 Mini
* **Key Capabilities**:
  \*
* **Tools**:
  * `catapa_employee_list_tool` - Retrieves list of employees in time range of analysis
  * `catapa_employee_education_tool`  - Retrieves education histories of employees
  * `catapa_employee_kpi_tool`  - Retrieves KPI score of employees
  * `catapa_employee_termination_tool`  - Retrieves termination entries of employees
  * `catapa_employee_job_experience_tool`  - Retrieves job experiences of employees
  * `catapa_master_data_education_level_tool`  - Retrieves master data of education level
  * `catapa_master_data_field_of_study_tool`  - Retrieves master data of field of study
  * `catapa_master_data_institution_tool`  - Retrieves master data of institution
  * `catapa_master_data_vendor_tool`  - Retrieves master data of vendor
  * `employee_promotion_tool`  - Retrieves promotions info of employees
  * `employee_salary_change_tool`  - Retrieves salary changes of employees
* **MCPs**: None
* **Tool Configurations**: CATAPA API credentials (tenant, base\_url, client\_id, client\_secret)

#### Tools Reference

<table><thead><tr><th width="408">Tool</th><th>Purpose</th></tr></thead><tbody><tr><td><code>catapa_employee_list_tool</code></td><td>Retrieves list of employees in time range of analysis</td></tr><tr><td><code>catapa_employee_education_tool</code></td><td>Retrieves education histories of employees</td></tr><tr><td><code>catapa_employee_kpi_tool</code></td><td>Retrieves KPI score of employees</td></tr><tr><td><code>catapa_employee_termination_tool</code></td><td>Retrieves termination entries of employees</td></tr><tr><td><code>catapa_employee_job_experience_tool</code></td><td>Retrieves job experiences of employees</td></tr><tr><td><code>catapa_master_data_education_level_tool</code></td><td>Retrieves master data of education level</td></tr><tr><td><code>catapa_master_data_field_of_study_tool</code></td><td>Retrieves master data of field of study</td></tr><tr><td><code>catapa_master_data_institution_tool</code></td><td>Retrieves master data of institution</td></tr><tr><td><code>catapa_master_data_vendor_tool</code></td><td>Retrieves master data of vendor</td></tr><tr><td><code>employee_promotion_tool</code></td><td>Retrieves promotions info of employees</td></tr><tr><td><code>employee_salary_change_tool</code></td><td>Retrieves salary changes of employees</td></tr></tbody></table>

***

### Code Snippet

Below is a code snippet showing how the Personnel Admin Digital Employee is created and configured. See the [full source code on GitHub](https://github.com/GDP-ADMIN/digital-employee/tree/main/common/applications).

{% code lineNumbers="true" %}

```python
def create_personnel_admin_agent(model: str = GPT_5_MINI_MODEL_NAME) -> DigitalEmployee:
    instruction = _load_instruction()
    quality_of_hire_agent = QualityOfHireAgent()
    job = DigitalEmployeeJob(
        title="Personnel Admin Coordinator",
        description=DESCRIPTION,
        instruction=instruction,
    )
    identity = DigitalEmployeeIdentity(
        name="Claudia",
        email="claudia@example.com",
        job=job,
    )
    configurations = [
        DigitalEmployeeConfiguration(key="CATAPA_TENANT", value=CATAPA_TENANT),
        DigitalEmployeeConfiguration(key="CATAPA_BASE_URL", value=CATAPA_BASE_URL),
        DigitalEmployeeConfiguration(key="CATAPA_CLIENT_ID", value=CATAPA_CLIENT_ID),
        DigitalEmployeeConfiguration(key="CATAPA_CLIENT_SECRET", value=CATAPA_CLIENT_SECRET),
    ]
    digital_employee = PersonnelAdminDigitalEmployee(
        identity=identity,
        tools=[
            time_tool,
            date_range_tool,
        ],
        sub_agents=[quality_of_hire_agent],
        mcps=[],
        configurations=configurations,
        model=model,
    )
    return digital_employee
```

{% endcode %}

This function:

1. Loads agent instructions from a markdown file (`personnel_admin_agent.md`).
2. Creates one sub-agents: `QualityOfHireAgent`.
3. Defines the job with title "Personnel Admin Coordinator", description, and instructions.
4. Creates the identity with name, email, and job.
5. Sets CATAPA API configurations (tenant, base url, client id and client secret).
6. Instantiates `PersonnelAdminDigitalEmployee` with:
   * Identity
   * Tools: time, date range
   * Sub-agents: quality of hire agent.
   * Configurations: CATAPA credentials
7. Deploys the digital employee.
8. Returns the deployed digital employee instance.

#### Usage Example

{% code lineNumbers="true" %}

```python
personnel_admin_agent = create_personnel_admin_agent()
result = personnel_admin_agent.run(message="List employees hired in 2026")
print(result)
```

{% endcode %}

***

### Environment Variables

This section describes all environment variables required to configure the Digital Employee Payroll Officer.

**AIP Configuration**

GDP Labs [AI Agents Package (AIP)](https://gdplabs.gitbook.io/gl-aip/getting-started/quick-start-guide/local-vs-remote#remote-mode) is the platform where the Digital Employee is deployed.

| Variable      | Description                                      |
| ------------- | ------------------------------------------------ |
| `AIP_API_URL` | Base URL of the AIP platform API                 |
| `AIP_API_KEY` | API key for authenticating with the AIP platform |

**CATAPA Configuration**

CATAPA is the HRIS system where payroll data is retrieved.

| Variable               | Description                                   |
| ---------------------- | --------------------------------------------- |
| `CATAPA_TENANT`        | Tenant ID to identify the company in CATAPA   |
| `CATAPA_BASE_URL`      | Base URL of the CATAPA API                    |
| `CATAPA_CLIENT_ID`     | OAuth 2.0 client ID for CATAPA API access     |
| `CATAPA_CLIENT_SECRET` | OAuth 2.0 client secret for CATAPA API access |

> **Note:** The CATAPA [OAuth](https://apps.catapa.com/dashboard/setup/settings/oauth-client) client must have full privileges for the following modules:
>
> * Payroll / Compensation & Benefits
> * Employee / Organization
> * Master Data

***

### CATAPA Setup

1. Create an [OAuth 2.0 Client](https://apps.catapa.com/dashboard/setup/admin-panel/oauth-client/add).

   * Client ID: preferably **`de_personnel_admin`**
   * Authorized Grant Type: **client\_credentials**
   * Client Access: grant full access to **Payroll**, **Employee**, and **Master Data**
   * Web Server Redirect URI: `https://catapa.com`
   * Click **Save**, then copy the generated **Client Secret**

   <div align="left" data-full-width="true"><figure><img src="https://2914931754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXbRDlxflF58D1QG2tLmP%2Fuploads%2FuAXKguX9JRiL1nKqm9FZ%2Fimage.png?alt=media&#x26;token=9067a171-492a-4a35-a5ed-768e7919b83a" alt=""><figcaption></figcaption></figure></div>
2. Provide the **Client ID**, **Client Secret** to the CATAPA infra team.

***

### References

* [DE Personnel Admin User Guide](https://gdplabs.gitbook.io/catapa/digital-employee-de/list-of-de/claudia-de-hr/claudia-de-quality-of-hire-analyst/user-guide)
* [GitHub Repository](https://github.com/GDP-ADMIN/CATAPA-API/tree/master/claudia/applications/digital-employee-payroll-officer)