> ## Documentation Index
> Fetch the complete documentation index at: https://www.botgauge.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your agent

> Connect an AI agent to BotGauge as an API endpoint or with the BotGauge wrapper. Form fields, environments, secrets, cURL import, and the four connection checks.

Open **Agents** under the **Red team** category and choose **Connect an agent**. BotGauge asks how to reach your agent, then tests the connection right on the page. Nothing is attacked yet.

## Choose how BotGauge reaches your agent

| Option | When to choose it |
| - | - |
| **API endpoint** | You have an HTTP agent. Fill in a short form, or paste a cURL. |
| **BotGauge Wrapper** | You can add a small endpoint to your agent. You only need a URL and a token. See [black box and grey box](https://www.botgauge.com/docs/red-teaming/black-box-and-grey-box.md). |

## Connection details

These fields tell BotGauge how to send a message and read the reply. To save typing, choose **Paste a cURL to fill this** and BotGauge fills the form from your command.

| Field | What to enter |
| - | - |
| Agent name | A name you will recognise, for example `Refund Concierge`. |
| Environment | **Staging**, **Test**, or **Production**. Production runs read-only attacks only. |
| Method | The HTTP method. `POST` for most chat endpoints. |
| Endpoint URL | The address that receives messages. |
| Auth header and Value | The header your agent needs, such as `Authorization`, and its value. Paste a key, or choose **Use a secret**. Keys are stored as secrets and never shown again. |
| Request body | The JSON your agent expects. Use a placeholder such as `{{message}}` where BotGauge's test message should go, for example `{ "message": "{{message}}" }`. BotGauge replaces it with each attack message. Choose **Edit** to change it. |
| Reply field | Where the reply text sits in the response. BotGauge puts each test message in `{{message}}` and reads the answer from this field. |
| Tool calls path (optional) | Where the reply lists the tools your agent called. If you leave it empty, the test looks for them. |

> [!NOTE]
>
> Attacks only go through chat, but your agent may still call its tools. Pick staging or test if you can.

### Use a secret for credentials

Choose **Use a secret** next to the Value field to pick an existing [project secret](https://www.botgauge.com/docs/platform/secrets.md), or choose **Add secret** to create one. In headers, a secret is referenced by name, for example `Bearer $ZENDESK_TOKEN`. BotGauge passes only the reference to the runner, never the value.

### Find your reply field

Call your agent once yourself and look at the JSON it returns. If the reply is at `{"data": {"reply": "Hi!"}}`, the reply field is `data.reply`.

### Session handling (optional)

If your agent keeps a conversation going by returning an id, tell BotGauge where to find it.

**Session ID path** is the location of the conversation id in your agent's reply. For example, if the reply is `{ "data": { "session_id": "abc123", "reply": "Hi!" } }`, the path is `data.session_id`.

BotGauge reads the id from the first reply and sends it back with each following message, so your agent sees one continuous conversation. The connection test then checks that the conversation continues and that separate conversations stay isolated.

Leave this empty if your agent doesn't return a session id. BotGauge then treats each message on its own, and the test reports that there is no continuity.

## Test the connection

Choose **Test connection**. BotGauge sends one test message and checks four things. Nothing is attacked, and the test takes about 10 seconds.

| Check | What it confirms |
| - | - |
| Can log in | The auth header is accepted. |
| Gets a reply | The answer is in the reply field. |
| Remembers the conversation | A detail is kept across turns. |
| Keeps conversations apart | Two chats run side by side and stay apart. |

If a check fails, the most common causes are these.

| Check that failed | Likely cause | Fix |
| - | - | - |
| Can log in | Missing or wrong auth header, or an expired key | Add the header, or update the [secret](https://www.botgauge.com/docs/platform/secrets.md). |
| Gets a reply | The reply field doesn't match your response | Call your agent yourself and copy the exact path to the reply text. |
| Remembers the conversation | Your agent treats each message as stand-alone | Check how your agent keeps session state. Results will say that multi-turn attacks are limited. |
| Keeps conversations apart | Two chats leak into each other | Fix session isolation in your agent. |

## No agent handy?

Choose **Use sample agent** to try the sample refund agent. Its results don't count. You can also open the sample agents already in your Agents list. See the [red teaming quickstart](https://www.botgauge.com/docs/red-teaming/quickstart.md).

Add your agent to BotGaugeFill in your endpoint and test the connection in [BotGauge](https://cloud.botgauge.com).

[Connect an agent →](https://cloud.botgauge.com)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.