Digital Employee Core

A Python library for building and managing AI-powered digital employees with support for tools, MCPs (Model Context Protocol), and flexible configuration management.

Documentation

For comprehensive developer documentation and guides, please refer to the Digital Employee Developer Documentation on GitBook.

Prerequisites

IDE Recommendation

We recommend using one of the following IDEs for developing with this library:

Option 1: PyCharm

Professional Python IDE with comprehensive features
Download: https://www.jetbrains.com/pycharm/
Editions: Professional (paid) or Community (free)

Option 2: Visual Studio Code (and its forks)

Lightweight, extensible editor with Python support
VSCode: https://code.visualstudio.com/
Cursor (AI-powered fork): https://www.cursor.com/
Windsurf (AI-enhanced fork): https://codeium.com/windsurf
Install the Python extension for full Python support

Python Installation

This project supports Python 3.11, 3.12, and 3.13.

Installation Instructions:

Linux/WSL:

# Ubuntu/Debian
sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-dev

# Fedora
sudo dnf install python3.12

macOS:

# Using Homebrew
brew install python@3.12

Windows:
- Download from python.org
- Or use pyenv-win for version management

Package Manager (uv)

This project uses uv as its package manager for fast and reliable dependency management.

Installation Instructions:

Linux/macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Alternative (using pip):
```
pip install uv
```
Verify Installation:
```
uv --version
```

For more information about uv, visit: https://docs.astral.sh/uv/

Setup

Automated Setup (Recommended)

For a complete automated setup that installs all prerequisites and configures the project, run:

./setup.sh

This script will:

Detect your operating system
Install Python 3.12 (if not already installed)
Install uv package manager (if not already installed)
Check/install gcloud CLI (optional, for private packages)
Install project dependencies via make install
Create a .env file template

Note: The script may require sudo privileges for installing system packages. After running the script, edit the .env file with your API credentials (see below).

Manual Setup

Alternatively, you can set up the project manually:

1. Install Dependencies

make install

2. Configure Environment

Copy the example environment file and add your credentials:

cp .env.example .env

Edit .env with your configuration:

# Required
AIP_API_URL=https://your-ai-platform-url.com
AIP_API_KEY=your-api-key

How to Obtain API Credentials:

To get the AIP_API_URL and AIP_API_KEY values, contact Squad 4 (Claudia) team:

Email: koi-claudia@gdplabs.id
Contact: berty.c.l.tobing@gdplabs.id

Tool-Specific Requirements

E2B Sandbox Tool

This tool requires an api_key parameter to be provided. You can either:

Pass the API key directly as a parameter when using the tool, or
Set the E2B_API_KEY environment variable (the tool will use this automatically if no parameter is provided)

Configuration Management

Understanding MCP Configuration Placeholders

The library uses YAML configuration templates (digital_employee_core/config_templates/mcp_configs.yaml and tool_configs.yaml) that contain placeholder keys in dollar-brace format (e.g., ${GOOGLE_CALENDAR_MCP_URL}). These placeholders need to be replaced with actual values at runtime.

How Placeholders Work:

Configuration Template (in mcp_configs.yaml):

digital_employee_google_calendar_mcp:
  config:
    url: ${GOOGLE_CALENDAR_MCP_URL}
    allowed_tools: ${GOOGLE_CALENDAR_MCP_ALLOWED_TOOLS:[]}
  authentication:
    type: api-key
    key: X-API-Key
    value: ${GOOGLE_MCP_X_API_KEY}

Supply Values using DigitalEmployeeConfiguration:

from digital_employee_core import DigitalEmployeeConfig

configurations = [
    DigitalEmployeeConfig(
        key="GOOGLE_CALENDAR_MCP_URL",
        value="https://api.example.com/calendar/mcp"
    ),
    DigitalEmployeeConfig(
        key="GOOGLE_MCP_X_API_KEY",
        value="your-secret-api-key"
    ),
]

Pass to Digital Employee:

from digital_employee_core import DigitalEmployee
from digital_employee_core.connectors.mcps import google_calendar_mcp

de = DigitalEmployee(
    identity=identity,
    mcps=[google_calendar_mcp],
    configs=configurations  # Placeholder values will be replaced automatically
)

de.deploy()

Available Placeholder Keys

For a complete and up-to-date list of available placeholder keys, refer to the configuration template files:

MCP Configurations: digital_employee_core/config_templates/mcp_configs.yaml
Tool Configurations: digital_employee_core/config_templates/tool_configs.yaml

Look for keys in the ${PLACEHOLDER_NAME} format within these files. Common categories include:

Google MCPs: Calendar, Docs, Drive, Mail, Sheets (+ shared GOOGLE_MCP_X_API_KEY)
GitHub MCP: URL and API key configurations
SQL Tool MCP: Database connection and authentication settings

Configuration Priority

Configurations can be supplied in three ways:

At Initialization (applied during deploy()):

de = DigitalEmployee(
    identity=identity,
    mcps=[google_calendar_mcp],
    configurations=configurations
)

At Runtime (applied per run() call):

response = de.run(
    message="Check my calendar",
    configurations=runtime_configurations
)

Combined (initialization configs + runtime configs are merged):

# Initialization configs for persistent settings
de = DigitalEmployee(
    identity=identity,
    configurations=base_configurations
)
de.deploy()

# Runtime configs for per-request overrides
response = de.run(
    message="Send email",
    configurations=request_specific_configurations
)

Run Examples

Basic Example

uv run python examples/basic_example.py

Subclass Example

uv run python examples/subclass_example.py

Run Tests

# Run unit tests (excludes integration tests)
make test

# Run with verbose output
uv run pytest -v

# Run with coverage report
make coverage

# Run with coverage HTML report
make coverage FORMAT=html
# Open htmlcov/index.html in browser

# Run specific test file
uv run pytest tests/digital_employee/test_core.py

Metadata

Release files for digital-employee-core 0.1.16

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for digital-employee-core 0.1.16
File	Size	Uploaded
digital_employee_core-0.1.16.tar.gz	49.9 kB	Sep 29, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for digital-employee-core 0.1.16
File	Interpreter	ABI	Platform	Reset
digital_employee_core-0.1.16-py3-none-any.whl 73.6 kB Sep 29, 2026	Python 3	none	any	Details

Total release size: 123.6 kB

Release files / digital_employee_core-0.1.16.tar.gz

Download URL	digital_employee_core-0.1.16.tar.gz
Size	49.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`22990d8be7369cd131b546605d442497cf370862fcb28a228a33cabb81dc8b23`
BLAKE2b-256 checksum How to use checksums	`b6e50f403e599e9005bd2df002ed5b6468091a351ec14039aae9b64957ba0d4b`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.20 {"installer":{"name":"uv","version":"0.12.20","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / digital_employee_core-0.1.16-py3-none-any.whl

Download URL	digital_employee_core-0.1.16-py3-none-any.whl
Size	73.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d86e18c8676b7f97af5113a3011fefeae646f50431ae7e67569163e4db73c110`
BLAKE2b-256 checksum How to use checksums	`a3787ee5469092970dc9083c4e6ffe2e9bf32e55cd8a9eaddca8635aae39704f`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.20 {"installer":{"name":"uv","version":"0.12.20","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`