Skip to main content

​
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: 
{
  "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: 
[
  {
    "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: 
{
  "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. 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:
FieldDescription
NameA display name for the tool
OpenAPI SchemaThe OpenAPI spec, upload a .json or .yaml file, or paste it directly
Default HeadersJSON object of headers to inject into every request
Default Query ParametersJSON object of query params to include on every request
Default Body ParametersJSON object of body fields to include on every request
Endpoint DefaultsJSON object of per-endpoint default overrides
Once submitted, the tool is immediately available to assign to an agent.
Custom ACI form fields:
FieldDescription
app.jsonDefines the application metadata and security scheme
function.jsonDefines the actions (functions) the agent can call
secrets.jsonProvides 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.