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

# Custom Tools

> Extend your agents with your own APIs and custom logic using OpenAPI specs or ACI integration files.

# Custom Tool Creation Using Studio

Lyzr's Custom Tools allow you to extend the platform by defining your own specialized actions and integrations. Seamlessly integrate your existing internal APIs and custom functionalities to equip your agents with unique capabilities that go beyond the pre-built integrations.

## Types of Custom Tools

Custom tools come in two types based on the integration method:

### 1. Custom OpenAPI Tools

Designed for connecting to any external service or API that follows the OpenAPI specification. Provide an OpenAPI spec file (JSON or YAML), and Lyzr automatically parses the schema, defining the tool's structure, available actions (endpoints), input parameters, and expected output format.

**Supported auth types:** No Auth, API Key.

**How it works:** Upload or paste your OpenAPI spec. Lyzr reads the endpoints and parameters directly from the spec. Authentication credentials are provided once during setup and injected into requests at execution time. Token refresh is not managed automatically, use ACI tools if you need OAuth with token lifecycle management.

**Best for:** Existing REST APIs and microservices with static authentication (no auth or API key).

### 2. Custom ACI Tools

ACI (Agent-Controlled Interface) is Lyzr's in-house integration layer, built on top of an open-source project. It goes beyond OpenAPI by adding full OAuth support, including acquiring access tokens, refreshing them automatically, and storing them encrypted.

**Supported auth types:** No Auth, API Key, OAuth 2.0 (with automatic token refresh and encrypted storage).

**How it works:** You provide three JSON files that together define the integration:

* **`app.json`**: describes the application, its metadata, and its security scheme (auth type, OAuth endpoints, scopes, client credentials). Sensitive values like client IDs and secrets are referenced as `{{ VARIABLE_NAME }}` placeholders here.
* **`function.json`**: defines the individual actions (functions) the agent can call, including their parameters, descriptions, and HTTP details.
* **`secrets.json`**: provides the actual values for the placeholders in `app.json`. This file is uploaded separately and its contents are encrypted and stored securely by Lyzr.

**Example `app.json`:**

```json theme={null}
{
  "name": "GMAIL",
  "display_name": "Gmail",
  "logo": "https://raw.githubusercontent.com/aipotheosis-labs/aipolabs-icons/refs/heads/main/apps/gmail.svg",
  "provider": "Google",
  "version": "1.0.0",
  "description": "The Gmail API is a RESTful API that enables sending, reading, and managing emails.",
  "security_schemes": {
    "oauth2": {
      "location": "header",
      "name": "Authorization",
      "prefix": "Bearer",
      "client_id": "{{ GMAIL_CLIENT_ID }}",
      "client_secret": "{{ GMAIL_CLIENT_SECRET }}",
      "scope": "https://www.googleapis.com/auth/gmail.send https://www.googleapis.com/auth/gmail.readonly",
      "authorize_url": "https://accounts.google.com/o/oauth2/v2/auth",
      "access_token_url": "https://oauth2.googleapis.com/token",
      "refresh_token_url": "https://oauth2.googleapis.com/token"
    }
  },
  "default_security_credentials_by_scheme": {},
  "categories": ["Communication"],
  "visibility": "public",
  "active": true
}
```

**Example `function.json`:**

```json theme={null}
[
  {
    "name": "GMAIL__SEND_EMAIL",
    "description": "Sends an email on behalf of the user",
    "tags": ["email"],
    "visibility": "public",
    "active": true,
    "protocol": "connector",
    "protocol_data": {},
    "parameters": {
      "type": "object",
      "properties": {
        "sender": {
          "type": "string",
          "description": "The user's email address. Use 'me' for the authenticated user.",
          "default": "me"
        },
        "recipient": {
          "type": "string",
          "description": "The email address of the recipient.",
          "format": "email"
        },
        "subject": {
          "type": "string",
          "description": "The subject of the email."
        },
        "body": {
          "type": "string",
          "description": "The plain text body of the email."
        }
      },
      "required": ["sender", "recipient", "body"],
      "visible": ["sender", "recipient", "subject", "body"],
      "additionalProperties": false
    }
  }
]
```

**Example `secrets.json`:**

```json theme={null}
{
  "GMAIL_CLIENT_ID": "your-client-id",
  "GMAIL_CLIENT_SECRET": "your-client-secret"
}
```

The keys in `secrets.json` must match the `{{ VARIABLE_NAME }}` placeholders used in `app.json`. These values are encrypted and stored securely by Lyzr, never in plaintext.

**Best for:** APIs that use OAuth 2.0, or any integration where token refresh and secure credential storage are required.

> Lyzr is actively open-sourcing the ACI tooling via [ACI.dev](https://aci.dev). Enterprise on-premise deployments can self-host the tooling layer, keeping all OAuth tokens and credentials within their own infrastructure.

***

## Adding a Custom Tool to Your Agent

### Step 1: Navigate to Tools

Go to **Tools** in the sidebar. This is the central management area for all tools, pre-built and custom.

### Step 2: Choose a tool type and fill in the form

Click **Add Tool** and select the type. The form differs depending on which type you choose.

**Custom OpenAPI form fields:**

| Field                    | Description                                                              |
| ------------------------ | ------------------------------------------------------------------------ |
| Name                     | A display name for the tool                                              |
| OpenAPI Schema           | The OpenAPI spec, upload a `.json` or `.yaml` file, or paste it directly |
| Default Headers          | JSON object of headers to inject into every request                      |
| Default Query Parameters | JSON object of query params to include on every request                  |
| Default Body Parameters  | JSON object of body fields to include on every request                   |
| Endpoint Defaults        | JSON object of per-endpoint default overrides                            |

Once submitted, the tool is immediately available to assign to an agent.

***

**Custom ACI form fields:**

| Field           | Description                                                                            |
| --------------- | -------------------------------------------------------------------------------------- |
| `app.json`      | Defines the application metadata and security scheme                                   |
| `function.json` | Defines the actions (functions) the agent can call                                     |
| `secrets.json`  | Provides the actual values for credential placeholders in `app.json`, stored encrypted |

After uploading the files, the tool is registered but **not yet ready to use**. You must complete the setup steps below before assigning it to an agent.

### Step 3: Complete ACI setup (ACI tools only)

#### 3a. Create a configuration

Before connecting an account, you need to create a configuration. This is where OAuth client credentials are set for the integration.

* For **OAuth** tools: choose to use the default client ID and secret provided by Lyzr, or supply your own.
* For **No Auth** and **API Key** tools: no configuration input is needed at this step, proceed to the next step.

#### 3b. Connect an account

With a configuration in place, connect the account that the tool will act on behalf of. How this works depends on the auth type:

* **No Auth**: the account is connected directly with no additional input.
* **API Key**: paste the API key value. It is stored encrypted and used in all requests.
* **OAuth 2.0**: you are redirected to the provider's authorization page to log in, grant permissions, and accept the requested scopes. After authorization, you are redirected back to Lyzr and the account is connected. ACI stores the access and refresh tokens encrypted and manages token renewal automatically.

Once an account is connected, the tool is ready to assign to an agent.

### Step 4: Assign to an agent

To assign the tool to an agent:

1. Open the Agent Builder → scroll to **Tools**
2. Select your custom tool from the list
3. Provide a **description** explaining when the agent should use this tool, this is critical for the LLM to route correctly
4. Save the agent

***

## Authentication Deep Dive

### No Auth

For public or internally trusted APIs that require no credentials. No additional configuration needed.

### API Key auth

Provide the key name and value during tool setup:

```
Key name: Authorization
Key value: Bearer sk-your-api-key
```

The key is stored encrypted and injected into request headers at execution time. Available for both OpenAPI and ACI tools.

### OAuth 2.0 auth (ACI only)

OAuth 2.0 is only supported via ACI tools. ACI handles the full token lifecycle, acquiring, storing, and refreshing tokens automatically. Tokens are stored encrypted.

**Shared auth** (single set of credentials for all users):

* Authenticate once during setup
* ACI stores and refreshes the token automatically

**Per-user auth** (each end user authenticates separately):

* Enable **per-user auth** in the tool settings
* Each user's OAuth flow is handled at inference time via a consent screen
* ACI manages individual token refresh cycles per user

***

## Deleting a Custom Tool

1. Navigate to **Tools** → locate the tool in the list
2. Click **Delete**
3. Confirm in the modal dialog

Deletion is permanent, all associated metadata, credentials, and configuration are removed.

***

## Best Practices

* **Write specific descriptions.** The LLM decides when to call a tool based on its name and description. Be precise: `"Retrieves the current weather for a city using the OpenWeather API"` is better than `"Gets weather"`.
* **Choose the right tool type.** Use OpenAPI for simple no-auth or API key APIs. Use ACI whenever OAuth is involved, it handles token refresh and encrypted storage that OpenAPI tools don't provide.
* **Test before deploying.** Use the built-in test runner with sample inputs before assigning the tool to production agents.
* **Use per-user auth for user-facing tools.** If your tool acts on behalf of end users (reading their calendar, sending from their email), always use per-user OAuth, not shared credentials.
* **Keep tools focused.** One tool per action is better than one tool that does many things. The LLM handles routing.