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.

Setup

This project supports Python 3.11, 3.12, and 3.13. Python 3.12 is the recommended development version.

1. Install Dependencies

poetry 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

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)

Hybrid Vector Retrieval Tool

This tool requires AWS credentials to be configured in the AIP environment where the digital employee is deployed.

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 DigitalEmployeeConfiguration

configurations = [
    DigitalEmployeeConfiguration(
        key="GOOGLE_CALENDAR_MCP_URL",
        value="https://api.example.com/calendar/mcp"
    ),
    DigitalEmployeeConfiguration(
        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],
    configurations=configurations  # Placeholder values will be replaced automatically
)

de.deploy()

Available Placeholder Keys

Refer to digital_employee_core/config_templates/mcp_configs.yaml and tool_configs.yaml to see all available placeholders. Common ones include:

Google MCPs:

GOOGLE_CALENDAR_MCP_URL
GOOGLE_CALENDAR_MCP_ALLOWED_TOOLS
GOOGLE_DOCS_MCP_URL
GOOGLE_DOCS_MCP_ALLOWED_TOOLS
GOOGLE_DRIVE_MCP_URL
GOOGLE_DRIVE_MCP_ALLOWED_TOOLS
GOOGLE_MAIL_MCP_URL
GOOGLE_MAIL_MCP_ALLOWED_TOOLS
GOOGLE_SHEETS_MCP_URL
GOOGLE_SHEETS_MCP_ALLOWED_TOOLS
GOOGLE_MCP_X_API_KEY

GitHub MCP:

GITHUB_MCP_URL
GITHUB_MCP_X_API_KEY

SQL Tool MCP:

SQL_TOOL_MCP_URL
SQL_AUTH_TOKEN
SQL_API_KEY
SQL_IDENTIFIER

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 Usage

poetry run python examples/basic_usage.py

Configuration Usage

poetry run python examples/configuration_usage.py

Subclass Example

poetry run python examples/subclass_example.py

Coordinator BYOK Model Example

MODEL_ID="openai/gpt-5.6-luna" \
MODEL_BASE_URL="https://api.openai.com/v1" \
MODEL_API_KEY="your_api_key_here" \
MODEL_HYPERPARAMETERS='{"reasoning": {"effort": "none"}}' \
poetry run python examples/byok_model_example.py

Additional BYOK examples for remote runs and subagent configuration are available in the examples directory.

MODEL_API_KEY may be loaded from .env or supplied in the environment. Set MODEL_ID and MODEL_BASE_URL directly in the environment or inline as shown above. If needed, set MODEL_HYPERPARAMETERS to a JSON object when supported.

When MODEL_ID and MODEL_BASE_URL are omitted, the examples default to openai/gpt-5.5 and https://api.openai.com/v1.

Run Tests

# Run all tests
poetry run pytest

# Run with verbose output
poetry run pytest -v

# Run with coverage
poetry run coverage run -m pytest
poetry run coverage report

# Run with coverage HTML report
poetry run coverage run -m pytest
poetry run coverage html
# Open htmlcov/index.html in browser

# Run specific test file
poetry run pytest tests/digital_employee/test_digital_employee.py

Metadata

Release files for digital-employee-core 0.0.42

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.0.42
File	Size	Uploaded
digital_employee_core-0.0.42.tar.gz	65.0 kB	Sep 18, 2026	Details

Built distribution (wheel)

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

Total release size: 160.4 kB

Release files / digital_employee_core-0.0.42.tar.gz

Download URL	digital_employee_core-0.0.42.tar.gz
Size	65.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`f6fd94f9ec4c1ee74253c43013e392055ced52271d01b145507870bff1df5cf2`
BLAKE2b-256 checksum How to use checksums	`dbf7b2613b961b2b23ab93aa157ab8979fce52b397aac03e5a1c01dfde10c2ef`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.2.1 CPython/3.12.3 Linux/6.14.0-1011-aws`

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

Download URL	digital_employee_core-0.0.42-py3-none-any.whl
Size	95.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`cea75fa067470e552e8b4c590713a071a04738e4c86bba4edffb254f5885aad1`
BLAKE2b-256 checksum How to use checksums	`86207b701bbd8219eee8c8ffcf7291423dd96948112ee23345fd069fb7452bc5`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.2.1 CPython/3.12.3 Linux/6.14.0-1011-aws`