Skip to main content

How to create an external agent

Step 1 - Open the AI Admin Panel

Click the Add Agent button to start creating a new agent.

Step 2 - Add a New Agent

Click the Add Agent button to start creating a new agent.

Step 3 - Choose Agent Type

Select External Agent from the available options. This type is used when your agent is managed outside the platform (e.g., OpenAI, Gemini, Anthropic, etc.).

Step 4 - Define Agent Details

Fill in the following fields:

  • Agent Name – The internal name for your agent in the platform (unique identifier).
  • Display Title – The visible name that appears in the platform UI and reports.
  • Department – The business or functional area this agent belongs to (e.g., Support, Sales, HR).
  • Manager – The owner or point of contact responsible for the agent’s configuration and performance.
  • Description – A short summary explaining the agent’s purpose or main function.

Step 5 - Continue to Configuration

Click Next to proceed to the configuration stage, where you’ll define the agent’s model, endpoints, and additional settings.

In this step, you’ll connect your external service to the platform by defining its endpoint, format, authentication, and safeguards.

Step 5.1 - Select Agent Provider​

Choose where your external agent is actually running. This controls which options and templates are available next and determines how requests are transformed.

  • Custom – Your own service, hosted on your infrastructure (any REST API).
  • AWS – An agent or model running on AWS (for example, Bedrock AgentCore).
  • CrewAI – An agent managed by CrewAI Enterprise.

Step 5.2 - Set the agent URL​

Enter the full HTTPS URL of your agent’s chat endpoint.
Example: https://yourcompany.com/chat

The complete URL endpoint of the external agent service that will process requests.

Make sure this URL:​

  • Is accessible from the public internet (or from our IPs if you’re restricting access).
  • Accepts POST requests with Content-Type: application/json.
  • Implements the request/response format described in External Agent Integration Requirements.

Step 5.3 - Configure Authentication & Headers​

If your external agent requires authentication:

  • Set Authentication Type (e.g., API Key, Bearer Token, Basic Auth) according to what your service supports.
  • Provide the required credentials (for example, API key value).

The platform will automatically:

  • Inject the credentials into the headers/query/body as needed.
  • Send them on every request to your /chat endpoint.

You can also add custom headers if your service expects additional fields (e.g. X-Org-Id, X-Environment).

Examples​

Here are a few common patterns and how to configure them:

  • Example 1 – API Key in header

    Your vendor’s docs say:
    “Send your API key in the X-API-Key header”
    with a key like: sk_live_123456.

    In the Authentication section:

    • Authentication Type: API Key
    • API Key value: sk_live_123456

    You don’t need to type X-API-Key yourself – the platform will add the correct header automatically.

  • Example 2 – Bearer token

    Your vendor’s docs say:
    “Use Bearer authentication with an access token”
    and show something like: Authorization: Bearer eyJhbGciOi....

    In the Authentication section:

    • Authentication Type: Bearer Token
    • Token: paste the full token string you received.

    The platform will send:
    Authorization: Bearer <your-token> on every request.

  • Example 3 – Extra header for environment

    Your vendor’s docs say:
    “Always include X-Environment: production in requests”.

    In Custom Headers:

    • Header Name: X-Environment
    • Header Value: production

    This header will be added to every call to your /chat endpoint.

Step 5.4 - Advanced Options​

These settings control how the platform behaves when calling your external agent.

Request Timeout​

  • What it is: The maximum time (in seconds) we wait for your external service to answer.
  • Default: 60 seconds.
  • How to think about it:
    If your agent is usually fast (2–5 seconds), you can keep the default.
    If your agent sometimes takes longer, you can increase this number slightly.
  • What happens if the time is exceeded:
    The request is stopped, and the user will see your fallback message instead of the agent’s answer.

HTTP Headers​

  • What it is: Extra pieces of information we can send with every request, as key–value pairs.
  • When to use:
    • Your external service expects a special header like X-Environment: production.
    • You need to pass a customer, tenant, or region ID such as X-Org-Id: acme_corp.
  • How to configure:
    1. Click “Add Header”.
    2. Enter the Header Name (for example: X-Environment).
    3. Enter the Header Value (for example: production).
  • These headers will be sent on every call to your /chat endpoint.

Fallback Message​

  • What it is: The message shown to your end users if the external agent cannot answer properly.
  • When it is used:
    • Your service is down or unreachable.
    • The request times out (takes longer than the Request Timeout).
    • The response is invalid or returns an error.
  • How to use it:
    • Write a clear, friendly message that does not expose technical details.
    • Example:

      “Sorry, something went wrong while contacting our assistant. Please try again later or contact support.”