Getting Started Example

This quickstart guide walks you through a simple setup to create a digital employee in just a few minutes.

Prerequisites

To follow this example, you will need to:

• Install the digital-employee-core package

• If you are planning to deploy and/or the digital employee in a remote AIP server, set the AIP_API_URL and AIP_API_KEY environment variables in your terminal or in a .env file

You should provide AIP_API_URL and AIP_API_KEY, because the digital employee depends on these two environment variables when you are using a remote AIP server.

To get the values for these environment variables, please ask your team which AIP server has been deployed, and then obtain the AIP key. For example, in CATAPA, we use AIP_API_URL=https://aip-dev.catapa.com/ as our AIP development environment.

You can set the environment variables in your terminal by using:

export AIP_API_URL=<AIP_API_URL>
export AIP_API_KEY=<AIP_API_KEY>

• If you are planning to run the digital employee locally, set the OPENAI_API_KEY environment variables in your terminal or in a .env file

Similar to AIP_API_URL and AIP_API_KEY, you can set OPENAI_API_KEY environment variable by using:

export OPENAI_API_KEY=<OPENAI_API_KEY>

Build Digital Employee - A Basic Example

Start by creating a simple digital employee that can interact with Gmail. This agent will use OpenAI GPT-5.1 as its language model, an MCP setup, and a simple prompt to guide its behavior.

Import the Package

from digital_employee_core import (
    DigitalEmployee,
    DigitalEmployeeConfiguration,
    DigitalEmployeeIdentity,
    DigitalEmployeeJob,
)
from digital_employee_core.connectors.mcps import google_mail_mcp

Initialize the Digital Employee

# Identity and configuration
job = DigitalEmployeeJob(
    title="Digital Assistant",
    description="A helpful digital employee assistant",
    instruction="You are a helpful digital employee assistant. When asked to send a welcome email, craft a warm, professional message that introduces the team and includes helpful resources. Do not ask for clarification, just proceed with sending the email.",
)
identity = DigitalEmployeeIdentity(name="Claudia", email="[e-mail]", job=job)
configurations = [
    DigitalEmployeeConfiguration(key="GOOGLE_MAIL_MCP_URL", value="https://api.bosa.id/google_mail/mcp"),
    DigitalEmployeeConfiguration(key="GOOGLE_MCP_X_API_KEY", value="[gl-connectors-x-api-key]"),
]

# Initialize digital employee
digital_employee = DigitalEmployee(identity=identity, configurations=configurations, mcps=[google_mail_mcp])

Run the Digital Employee Locally

# Run the digital employee locally using a prompt
result = digital_employee.run(
    message="Send a welcome email to [your-email] welcoming them to the team. Include a warm greeting, mention that you're excited to have them on board, and let them know you're here to help with any questions.",
    local=True
)
print(result)

Run the Digital Employee in Remote AIP Server

# Deploy the digital employee to AIP server
digital_employee.deploy()

# Run the deployed digital employee using a prompt
result = digital_employee.run(message="Send a welcome email to [your-email] welcoming them to the team. Include a warm greeting, mention that you're excited to have them on board, and let them know you're here to help with any questions.")
print(result)

Before running the sample code, replace the following placeholders:

1. Replace [your-email] with your email address.

2. Replace [gl-connectors-x-api-key] with x-api-key from GL Connectors. See below for one way to do it.

3. (Optional) Replace GOOGLE_MAIL_MCP_URL if you are using a different GL Connectors server instance.

🔑 Get GL Connectors x-api-key

1. Open https://api.bosa.id/console, then sign in.

2. In the Credentials section, expand the x-api-key panel and click Copy combined value button. Paste this value to replace [gl-connectors-x-api-key] .

1. If your Gmail account has not been integrated yet, continue with the steps below.

2. Under Available Modules section, find the Google_mail integration and click Add New Integration button.

1. An authorization URL will appear. Click or copy the URL, then authenticate using your Gmail account.

1. Below is an example of a successfully integrated Gmail account.