Extending Your Agents: Creating Custom API Tools

Our Agent platform comes with many powerful built-in capabilities, but its true strength lies in its extensibility. You can turn almost any external API into a "Tool" that your Agents can use, allowing them to interact with your custom systems, internal applications, or specialized third-party services.

This deep dive will guide semi-technical users through the process of creating custom API Tools, explaining the two key steps: registering your API for authentication and defining its functional schema.

The Power of Custom API Tools

Imagine you have an internal system for managing inventory, a unique CRM, or a niche financial API. By transforming these into Agent Tools, you empower your Agents to:

Automate specialized workflows: Have an Agent update your custom inventory system when stock runs low.
Access proprietary data: Enable an Agent to pull specific data from your internal dashboards.
Integrate with niche services: Let your Agent interact with any API, regardless of how obscure.

This means your Agents aren't just generic assistants; they become tailor-made extensions of your entire digital ecosystem.

Step 1: Connecting Your API - The Integration (Authentication)

Before an Agent can use an API, our system needs to know how to securely connect and authenticate with it. This is handled by registering your API as an Integration.

This step is about securely storing the "keys" (like API tokens or credentials) that your Agent will use to prove its identity to the external API.

You typically do this by providing the following information through a dedicated integration setup:

provider: A unique name for the API you're connecting (e.g., "MyCustomCRM", "InternalInventoryAPI").
token_input: This is where you provide the actual authentication credentials. This might be an API key, an OAuth token, or other specific login details required by the external API. Our system will securely encrypt and store this information.
account_alias: A friendly name to identify this specific connection (e.g., "Production CRM", "Sandbox Inventory"). Useful if you have multiple accounts for the same provider.
auth_type (Optional): Specifies the type of authentication (e.g., "bearer" for Bearer Tokens, "api_key", "basic_auth"). This helps our system format the authentication details correctly.
auth_schema (Optional): More complex authentication methods might require a specific JSON structure for their token_input. This schema helps ensure you provide the data in the correct format.

Behind the Scenes: When you "link an API account" (as seen in our link_api_account endpoint), our system takes these details, processes the token_input using a specific handler for that provider, and securely stores the encrypted credentials in our database, tied to your tenant_id and user_id. This means your Agents can access the API without you ever needing to hardcode sensitive information into the Tool's definition.

Step 2: Defining the Tool's Functionality - The Schema

Once your API is integrated (i.e., we know how to authenticate with it), you need to tell the Agent how to use its specific endpoints. This is done by creating a Tool Schema.

A Tool Schema is essentially a blueprint that describes a specific API call an Agent can make. It tells the Agent:

Which URL to hit.
What type of request to make (GET, POST, PUT, DELETE, GRAPHQL).
What information it needs to send.
What kind of response to expect (optionally).

You have two primary ways to create these schemas:

A) Manual Schema Definition (For the Detail-Oriented)

For users who prefer precise control and are familiar with API documentation, you can define the schema manually using a structured JSON format. A Tool Schema consists of:

name: A short, descriptive, human-friendly name for the Tool's purpose (e.g., "Search Customer by ID", "Create New Order"). This helps the Agent's AI understand when to use this Tool.
config: This section provides the core details for making the HTTP request to your API:
- base_url: The root domain of the API (e.g., https://api.mycrm.com/v1).
- endpoint: The specific path for this operation (e.g., /customers/{customer_id}, /orders).
- method: The HTTP method to use. We support:
  - GET: To retrieve data.
  - POST: To create new data.
  - PUT: To completely replace existing data.
  - DELETE: To remove data.
  - GRAPHQL: For GraphQL API queries or mutations.
- headers (Optional): Any static HTTP headers required for every request (e.g., {"Content-Type": "application/json"}).
input_schema: This is a crucial part, defining what information the Agent needs to provide to the Tool, following the JSON Schema standard. It tells the Agent the names of the parameters, their expected data types, and whether they are required.
- type: "object": Indicates the input is a JSON object.
- required: ["param1", "param2"]: A list of parameters the Agent must provide.
- properties: Defines each parameter with:
  - "type": (e.g., "string", "integer", "boolean")
  - "description": A clear explanation of what the parameter is for (very important for the Agent's AI!).
  - "enum" (Optional): A list of allowed values (e.g., ["USD", "EUR", "GBP"]).
  - "default" (Optional): A default value if the Agent doesn't specify one.
Example input_schema:
```
{
  "type": "object",
  "required": ["customer_id"],
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "Unique identifier for the customer to retrieve."
    },
    "include_orders": {
      "type": "boolean",
      "default": false,
      "description": "Set to true to also retrieve the customer's order history."
    }
  }
}
```
output_schema (Optional): If you confidently know the structure of the API's response, you can define an output_schema using JSON Schema format. This helps the Agent better understand the data it receives back from the Tool.

Special Case: GraphQL API Tools

If your API uses GraphQL, the schema definition has a slight variation:

The method in config should be set to "GRAPHQL".
You must include a top-level "query" field in your config that contains the raw GraphQL query string (e.g., { customer(id: $id) { name email } }).
Instead of passing input variables directly as properties in the input_schema, they should be nested under a variables object in your input_schema (e.g., { "type": "object", "properties": { "variables": { "type": "object", "properties": { "id": { "type": "string" } } } } }).

B) Assisted Schema Creation (The "Schema Assistant")

Don't want to dig through API docs and write JSON Schema by hand? Our Schema Assistant simplifies the process using AI!

How it Works: You can provide:
1. A URL to a specific page of the API's documentation: Our system will fetch the content of that page, read it (using components like _fetch_schema_docs), and analyze it.
2. A natural language description: Simply tell the system, "I want a tool to search for products by name and category."
AI-Powered Generation: Our Agent's underlying AI (LLMService.generate_inputs within _generate_api_schema) will then intelligently interpret the documentation or your description. It will use its understanding of APIs and JSON Schema to automatically generate the name, config, and input_schema (and optionally output_schema) for you.
Benefits: This dramatically speeds up Tool creation, reduces human error, and makes integrating complex APIs accessible even to those less familiar with strict API specifications. You can always review and fine-tune the AI-generated schema.

Bringing It All Together

Once you've:

Connected your API by registering its authentication details (Step 1), and
Defined its functionality by creating a Tool Schema (Step 2, either manually or with the assistant),

...your custom API is now a fully functional "Tool" in our system. You can then attach this Tool to your Agents, and their AI brains will automatically understand when and how to use it to achieve their goals, securely accessing and interacting with your external systems.

The Power of Custom API Tools​

Step 1: Connecting Your API - The Integration (Authentication)​

Step 2: Defining the Tool's Functionality - The Schema​

A) Manual Schema Definition (For the Detail-Oriented)​

Special Case: GraphQL API Tools​

B) Assisted Schema Creation (The "Schema Assistant")​

Bringing It All Together​