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

# Use Custom APIs in an Agent

> Attach a REST API connector to an Agent, set Auto, Ask or Block for each operation, test it and remove it from the Agent.

<Info icon="plug">
  This page shows how to use a **REST API connector** that already exists in the Workspace inside an Agent. If you don't have one yet, create it first in [Custom API connectors in the Space](/en/custom-api-connectors).
</Info>

## Entry point

**My agents** → open an Agent → **Build** → **Configuration** panel → **Connectors** section → **+**.

## Attach the Connector to an Agent

<Steps>
  <Step title="Open the Agent's Connectors section">
    Open the Agent. On the **Build** screen, select the **Configuration** panel and click **+** in the **Connectors** section.
  </Step>

  <Step title="Choose the account type">
    Choose **Shared** (one Workspace account) or **Per-user** (each person's own account).

    <img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/en_agent_connector_add_menu.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=e2e4574deb4683c9896a4326731c4426" alt="Menu with Shared and Per-user" width="1568" height="706" data-path="images/en_agent_connector_add_menu.jpg" />
  </Step>

  <Step title="Select the Connector and click Done">
    Custom Connectors are listed together with the built-in ones. Select the Connector and click **Done**. **Create connector** at the bottom opens the same REST API dialog as the Connectors page.

    <img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/en_agent_connector_picker.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=ded21de7bdb5077a2b0d97b950ce0d98" alt="Shared Connectors picker with Demo Orders API selected" width="1568" height="706" data-path="images/en_agent_connector_picker.jpg" />
  </Step>

  <Step title="Expand the Connector to see its operations">
    The Connector appears in the **Connectors** section with its account type and the number of exceptions. Click the row to see the account in use and the permission of each operation.

    <img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/en_agent_connector_permissions.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=86f23181e67ae34d6cadf555b2b85313" alt="Attached Connector with the default permission of each operation" width="1568" height="706" data-path="images/en_agent_connector_permissions.jpg" />
  </Step>
</Steps>

| Account type | When the Agent runs | Use it when |
| - | - | - |
| **Shared** | The Agent always uses the same Workspace account, no matter who is asking | Shared business APIs with a key issued by an admin |
| **Per-user** | Each person connects and uses their own account | Each person has their own key or permissions on the API |

With **Shared**, the **Account** area shows which account the Agent uses. Click the switch icon to pick another account, **Add account** or **Manage accounts**.

<img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/en_agent_connector_account.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=1dacc7bcd9a7e8795b890e7de836a103" alt="Account menu for a Shared Connector" width="1568" height="706" data-path="images/en_agent_connector_account.jpg" />

With **Per-user**, there is no Account area. If a person hasn't connected their own account yet, the Agent tells them to connect it before it calls an operation.

<img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/en_agent_connector_peruser.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=3e579d479f420abda7ca8066bf83688c" alt="Connector attached as Per-user" width="1568" height="706" data-path="images/en_agent_connector_peruser.jpg" />

<Note>
  On one Agent, a Connector can be attached with only one account type. A Connector already attached as Shared shows **Already added · Shared** in the Per-user picker. To switch types, remove the Connector and attach it again.
</Note>

## Set a permission for each operation

Each operation has three permission levels:

| Level | What the Agent does | Default for |
| - | - | - |
| **Auto** | Calls the API right away without asking | **Read-only** operations |
| **Ask** | Stops and asks the user to approve before calling | **Writes data** and **Can destroy data** operations |
| **Block** | Can't call this operation | No default, you set it |

The **exceptions** count next to the Connector name tells you how many operations differ from their default. The example below sets **Cancel an order** to **Block** so the Agent can't cancel orders.

<img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/en_agent_connector_block.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=0fa286155976b59be5da5878c59bfb89" alt="Cancel an order set to Block" width="1568" height="706" data-path="images/en_agent_connector_block.jpg" />

<Tip>
  Removing and re-attaching a Connector resets every operation to its default permission. Note your exceptions before you remove it.
</Tip>

## Test the Agent with the Connector

<Steps>
  <Step title="Send a request on the Test run tab">
    Open the **Test run** tab and send a request that needs the API, for example: Create an order for customer Tran Thi B with a total of 250000.
  </Step>

  <Step title="Approve or reject the action">
    For an operation set to **Ask**, the **Action needs your approval** card shows the operation and the arguments the Agent wants to send. Click **Approve** to call the API. Click **Reject** to skip the call, optionally with a **Rejection reason** so the Agent can adjust.

    <img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/en_agent_approval_card.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=751584b432e9bb3dc7615917fcbaa9c4" alt="Action needs your approval card for create_order" width="1568" height="706" data-path="images/en_agent_approval_card.jpg" />
  </Step>

  <Step title="Check the arguments and the result">
    After the Agent replies, expand **Used N tools** and then the tool name to see the **Arguments** that were sent and the **Result** the API returned.

    <img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/en_agent_tool_result.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=4769ae03c705e990c5b9664c2a8e7ba4" alt="Details of the create_order call with arguments and result" width="1568" height="706" data-path="images/en_agent_tool_result.jpg" />
  </Step>
</Steps>

<Warning>
  A test run calls the real API and spends real Workspace tokens. When you test operations that write or delete data, point the Connector at a test environment of the API.
</Warning>

<Note>
  Connector changes in an Agent are auto-saved to the draft. End users only see them after you Publish a new version of the Agent.
</Note>

## Remove the Connector from an Agent

Click the **trash** icon on the Connector row in the **Connectors** section. The Connector is removed right away, with no confirmation dialog. It stays in the Workspace and you can attach it again at any time.

<Note>
  When the Connector is re-imported in the Space, operations removed or renamed in the new document are no longer available in the Agent. Open the Agent's **Connectors** section to check permissions and run a test again.
</Note>

## Troubleshooting

| What you see | Cause | Fix |
| - | - | - |
| The Agent asks the user to connect an account | The Connector is attached as **Per-user** and the user hasn't connected yet | The user connects their own account before using the Agent |

## See also

<CardGroup cols={2}>
  <Card title="Custom API connectors in the Space" icon="plug" href="/en/custom-api-connectors">
    Create, edit, re-import and delete Connectors.
  </Card>

  <Card title="Connectors" icon="link" href="/en/connections">
    How to attach built-in Connectors and set tool permissions.
  </Card>
</CardGroup>


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