Custom Integrations

Custom Apps let you connect any external API to Ema so your AI Employees can use it directly. Whether you need to reach an internal system, a niche SaaS product, or a third-party service, you can build a Custom App for it. Once it is set up, you can add as many actions as you need -- and your AI Employees will be able to call them during their workflows.

When to Build a Custom Integration

• You need an AI Employee to call an internal microservice or a niche SaaS product not yet in the Ema catalog.
• You want to wrap a third-party REST or GraphQL endpoint as a reusable tool that multiple AI Employees can share.
• You have an on-premises system exposed through an API gateway and want Ema to interact with it securely.

Getting Started

Getting a Custom App action running takes four steps:

1. Create a Custom App -- Define the integration (name, category, description) on the Integrations page.
2. Connect and configure authentication -- Set up the auth scheme (API Key or OAuth 2.0), define credential fields, and establish a live connection.
3. Build and test actions -- Create actions, write the API call logic using call_ema_connector in a Custom Code agent, define inputs and outputs, and run the persona.
4. Add to an AI Employee -- Add the registered action as a tool in an AI Employee's workflow using Intelligent Actions so it can be invoked at runtime.

Key Concepts

Building a Custom Integration

Step 1 -- Create a Custom App

1. Navigate to the Integrations page.
2. Click New Custom App in the top-right corner.
3. In the modal that opens, fill in the required fields:
   • Application name -- enter a unique name (letters, numbers, and spaces only).
   • Category -- select a category from the dropdown (for example, CRM, Productivity, Custom).
   • Description -- describe what this integration does. This text is shown on the Integrations page.
4. Click Confirm.

The new Custom App appears in the integrations homepage under all apps.

Step 2 -- Connect and Configure Authentication

Authentication setup walks you through defining your auth scheme, filling in credentials, and establishing a connection. The steps differ depending on whether you choose API Key or OAuth 2.0.

Start the connection wizard

1. Open the Custom App by clicking its card on the Integrations page.
2. In the Overview tab, locate the Intelligent Actions integration banner and click Connect.
3. A Connection options dropdown appears. Select your auth type:
   • API Key -- for services that authenticate with a static key or token.
   • OAuth 2.0 -- for services that use the OAuth 2.0 authorization flow.

Phase 1 -- Define the auth configuration

This phase collects the Base URL, scheme-specific settings, and auth field definitions. Refer to your external API's documentation to determine the correct values for each field.

1. In the setup modal, enter the Base URL -- the root URL of the API (for example, https://api.linear.app/graphql). This field is always required.
2. If you selected OAuth 2.0, fill in these additional fields:
   • Auth URL -- the authorization endpoint.
   • Token URL -- the token endpoint.
   • Scopes -- comma-separated OAuth scopes (optional).
   • A read-only Redirect URI is displayed for you to copy and register with the OAuth provider.
3. If you selected API Key, the Connection Fields section is pre-populated with a default field:
   • Field Name: api_key
   • Display Name: API Key
   • Placement: Custom Header
   • Header Name: Authorization
   • Secret: checked

   You can edit these defaults or add more fields to match your API's requirements.

Configure Template Fields and Connection Fields. Both field types share the same structure -- the difference is who provides the value and when:

• Template Fields are set once during integration setup and shared across all connections. Use these for credentials that belong to the integration itself.
• Connection Fields are filled in each time a connection is created. Use these for credentials that are specific to a user or environment.

For each field, provide:

• Field Name -- a machine-readable identifier. Check your API documentation for the expected parameter name.
• Display Name -- the label shown to users.
• Placement -- where the value is injected into outgoing HTTP requests:
  • Bearer Token -- sent as Authorization: Bearer <value>.
  • Custom Header -- sent as a custom HTTP header (specify Header Name).
  • Query Parameter -- appended to the URL (specify Param Name, for example api_key).
  • JSON Body -- included in the request body as JSON (specify Field Name).
  • Form Body -- included in the request body as form data (specify Field Name).
• Check Secret to mask the value in the UI.

Click Save & Continue.

Phase 2 -- Fill template credentials

If your auth scheme has template-level fields, you are prompted to fill in their values. Enter values for each template field shown in the form and click Save & Continue.

Phase 3 -- Enter connection credentials

This is where you provide the actual credentials for the connection:

• API Key: Enter your API key value in the field shown.
• OAuth 2.0: Enter any runtime connection fields required by the provider.

Click Connect when done.

Phase 4 -- Complete the connection

• API Key: The connection is established immediately. A success toast confirms the connection.
• OAuth 2.0: A browser popup opens to the OAuth provider's authorization page. Complete the sign-in flow in the popup. Once authorized, the popup closes and the connection is established.

On success, the banner button changes from Connect to Disconnect, and your actions can now execute against the API.

Step 3 -- Create an Action

1. Open the Custom App modal and navigate to the Actions tab.
2. Click New action.
3. Enter a Name and Description for the action.
4. Click Confirm.

A new browser tab opens to the Action Builder (GWE canvas) with the configuration modal pre-opened.

Build an Action

After clicking Confirm, the Action Builder persona opens in a new tab. This is the same GWE canvas used for AI Employees, but scoped to the three agents available in actions: Custom Code Agent, Convert to Text, and Custom Agent.

The canvas opens with a pre-configured trigger and a default workflow input called tool_input. You need to complete three things before the action can be saved and registered: define your inputs, write the workflow logic, and declare at least one named output.

Define workflow inputs

Workflow inputs become the action's input parameters -- the values an AI Employee supplies when it calls this tool. The canvas starts with a default tool_input input. You can edit it or add more.

Open the trigger node and click to add or edit a workflow input. For each input, provide:

• Name and Display name -- the machine name and human-readable label.
• Description -- helps the AI Employee understand what value to pass. Write this clearly -- it directly affects how well the AI selects and fills this parameter.
• Type -- select the data type (String, Int, Float, Boolean, Date, DateTime, Object, Array, and others).
• Required -- whether the AI Employee must provide this value.

Optionally, expand Additional parameters to configure advanced settings:

• Input dependencies -- declare that this input depends on the output of another action within the same Custom App.
• User ID domain -- indicate that this input represents a user identity (Email or MS Active Directory ID). When set, Ema auto-fills the value from the actioning user's identity.

Build the workflow on the canvas

Use the visual canvas to define the action's logic. Actions support three agents:

• Custom Code Agent -- write JavaScript to call the external API and process the response.
• Convert to Text -- convert any input types into a single text string without using LLMs.
• Custom Agent -- a configurable agent where you define a role, task instructions, and a structured output schema. The Custom Agent uses an LLM to carry out the described task -- useful for summarizing API responses, classifying data, extracting fields from unstructured text, or making decisions based on returned data. Unlike Custom Code (which runs deterministic JavaScript), the Custom Agent handles tasks that benefit from language understanding.

Writing the API call with Custom Code

The Custom Code agent uses call_ema_connector -- a built-in JavaScript function that makes authenticated HTTP calls through Ema's proxy. Ema automatically injects your stored credentials (API key or OAuth token) into every request.

Function signature:

call_ema_connector(integration_id, method, path, body?, headers?)
// Returns: { ok, status, body, headers, request_log_id }

Parameters:

Response object:

Restrictions and limits:

Building the workflow

1. Click the Add Agent button on the canvas to add an agent step.
2. Select Custom Code Agent to write a script, Convert to Text to transform data, or Custom Agent for configurable task execution.
3. Connect the steps with edges to define data flow.
4. Reference workflow inputs in your script using inputs.<input_name>.
5. Return the data you want to pass to downstream steps or to the named output.

Define named outputs

Named outputs define what the action returns to the AI Employee. At least one named output is required -- without it, the action cannot be saved or registered as a tool.

1. Open the Named Results panel on the right side of the canvas.
2. Add one or more named results. For each, provide:
   • Name -- identifier for the output.
   • Description -- explain what this output contains.
   • Type -- the data type of the returned value.

Save and register the action

Click Save Changes in the canvas header. On save, Ema automatically registers the action as an external tool in the action registry. No separate publish step is needed.

The action is now discoverable by any AI Employee in your workspace. Every subsequent save re-registers the action with any updated inputs, outputs, or logic.

Test an Action

Actions are fully runnable personas. You can test them in two ways: directly from the Custom Code agent during development, and from the dashboard as a full end-to-end run.

Test from the Custom Code agent

While building your script in the Custom Code agent, you can run it directly to verify your API calls work:

1. In the Custom Code agent node on the canvas, write or edit your script.
2. Use the Test button within the agent to execute the script.
3. The agent makes live call_ema_connector calls against the real API.
4. Review the script output inline to confirm the response shape and values.

This is useful for iterating quickly on your script logic -- checking response parsing, error handling, and field mapping -- without running the full workflow.

Test from the dashboard

For a full end-to-end test that exercises the entire workflow (trigger, inputs, agents, and named outputs):

1. In the Action Builder canvas, click Use AI Employee in the top-right header.
2. This opens the dashboard view for the action's persona.
3. Add a row with test input values (for example, a sample ticket title or user email).
4. Run the workflow. Ema executes the full flow -- including all call_ema_connector calls -- against the live API.
5. Review the output rows in the dashboard results. Each run produces a row showing the named output values.

You can add multiple rows with different input combinations to test various scenarios in a single session.

What to verify

• Correct API calls: Check that the right endpoints are hit with the right method and payload. Use the request_log_id from the response to correlate with request logs.
• Auth works end-to-end: If you see authentication errors (401/403), verify your connection credentials in the Custom App settings (Step 2).
• Error handling: Test with invalid inputs, missing fields, and edge cases. Confirm your script handles non-2xx responses gracefully rather than silently failing.
• Output shape: Verify that the named outputs contain the expected data and types. The output schema is what AI Employees see when they consume this tool.
• Connection status: The Custom App must be connected for test runs to succeed. If disconnected, the call_ema_connector calls will fail.

Run an Action in GWE Using Intelligent Actions

Once an action is saved and registered, it is available as a tool and must be added to an AI Employee before it can execute in production workflows.

Add the tool to an AI Employee

1. Navigate to AI Employees and open any AI Employee of your choice, or create a new one.
2. In the canvas, click to add a tool step.
3. In the Select App modal, find and select your Custom App from the list.
4. The Tools tab opens showing all registered actions for this Custom App. Click the action you want to add.
5. In the Configure Tool modal, set up each input parameter:
   • Auto fill by Ema -- the AI Employee infers the value at runtime based on conversation context. Use this for dynamic inputs like user queries, email content, or extracted entities.
   • Fixed value -- you provide a constant value that is used every time the tool runs. Use this for static config like environment names, default statuses, or fixed IDs.
6. Optionally, enable HITL -- when checked, the AI Employee pauses before executing this tool and presents the proposed parameters for human approval. The tool only runs after the human confirms.
7. Click Save.

What happens at runtime

When an AI Employee invokes a Custom App action during a workflow:

1. The Intelligent Actions framework identifies that the action matches the current task and calls the action.
2. The Workflow Engine executes the action synchronously.
3. The Custom Code agent runs your JavaScript. Each call_ema_connector call is routed through EmaConnector, which resolves the tenant's stored credentials, injects authentication, and forwards the request to the external API.
4. The external API responds. EmaConnector returns the response to your script.
5. Your script processes the response and returns the result.
6. The workflow's named outputs are returned to the AI Employee as the tool response.
7. The AI Employee uses the returned data in subsequent workflow steps.

Runtime behavior and limits

Managing Custom Apps

Editing a Custom App

1. Open the Custom App modal from the Integrations page.
2. Click the pencil icon (Edit integration) in the header.
3. Update any combination of Application name, Category, Description, Base URL, auth URLs, or auth fields.
4. Click Save Changes.

Unsaved changes are discarded if you close the modal without saving.

Exporting and importing

Export:

1. Open the Custom App modal and go to the Actions tab.
2. Click Export (visible only when the app has at least one action).
3. Follow the export wizard to generate a portable definition of the app's actions.

Import:

1. On the Integrations page, click Import in the top-right corner.
2. Follow the import wizard to upload a previously exported definition.
3. The imported Custom App and its actions appear in the integration list.

Deleting a Custom App

1. Open the Custom App modal.
2. Click the trash icon (Delete integration) in the header.
3. A confirmation dialog appears.

Click Delete to confirm, or Cancel to go back.

Best Practices

• Write clear descriptions. The Intelligent Actions agent relies on tool and action descriptions to decide which tool to invoke. Ambiguous descriptions lead to incorrect tool selection.
• Define all required parameters explicitly. If a required parameter is missing, the API call will fail at runtime.
• Test before enabling. Use the Custom Code agent's test button and the dashboard view (Use AI Employee) to catch errors before adding the action to a production workflow.
• Keep actions granular. Define one action per distinct operation rather than combining multiple operations into a single action.
• Rotate credentials proactively. Use maintenance mode when rotating API keys or OAuth secrets to avoid transient failures.
• Always check for API errors in your script. If you do not add error handling, your action might look like it worked even when the API call actually failed -- returning empty or incorrect data without any warning.
• Write descriptive workflow input descriptions. The AI Employee uses input descriptions to decide what value to pass at runtime. Vague descriptions like "ID" lead to incorrect parameter mapping -- use something like "The unique project ID returned by the Get Projects action."
• Enable HITL for high-impact write actions. For actions that create, update, or delete data (for example, "Create Ticket" or "Delete User"), enable Human-in-the-Loop so a human can review parameters before execution.
• Use named outputs with accurate types. The output schema is what AI Employees see when consuming the tool. Mismatched types or vague names cause downstream steps to misinterpret the data.

FAQ

• Can I create a Custom App with the same name as a pre-built integration? No. App names are checked case-insensitively across all integrations -- pre-built and custom. Choose a unique name.
• What happens to actions if I delete the Custom App? All actions tied to the deleted app are marked as deprecated and will no longer run during AI Employee execution. Any AI Employees consuming those tools are flagged as broken. This is irreversible.
• What characters are allowed in the app name? Only letters, numbers, and spaces. Special characters and symbols are not permitted.
• Can I rename the Tool ID after creating an action? No. The tool_id is auto-generated from the action name at creation time and is immutable. If you need a different Tool ID, delete the action and create a new one.

Limitations

• Custom tool integrations currently support HTTP-based APIs only. gRPC, WebSocket, and other protocols are not supported.
• Custom data connectors (for importing content into Ema's knowledge base) are under development and not yet available.
• File upload as part of a custom tool action is not supported in the current release.
• Each Custom App supports only one connection per tenant. You cannot configure multiple connections (for example, for different environments or users) under the same integration.
• There is no version history for actions. Every save overwrites the previous configuration immediately with no rollback option.

Related

• Custom Tool Integrations (Workflow Building) -- Detailed reference for building custom tools in the workflow builder.
• Intelligent Actions -- How the Intelligent Actions agent selects and executes tools.
• Integration List -- Full catalog of pre-built connectors.