Custom tools let Duckie call HTTP endpoints that you define. Use them for internal services, third-party APIs, or any API action that is not already covered by a connected integration.Documentation Index
Fetch the complete documentation index at: https://docs.duckie.ai/llms.txt
Use this file to discover all available pages before exploring further.
Create a Custom Tool
Add basic details
Enter a name and description. The description helps the agent understand when to use the tool.
Configure the endpoint
Choose a method and enter the endpoint URL.Supported methods are
GET, POST, PUT, PATCH, and DELETE.Choose authentication
Select an OAuth credential for OAuth 2.0 client credentials, or leave No OAuth and add authentication headers manually.
Add headers
Add any non-OAuth headers the endpoint requires, such as API keys, vendor headers, or content type headers.
Enable a Custom Tool
After creating a custom tool, choose where it can be used:| Surface | How to use the tool |
|---|---|
| Agents | Open the agent’s tool access settings and enable the custom tool |
| Internal assistant | Open Settings > Assistant and enable the custom tool |
| Workflows | Add an Action node, open the Custom tab, and select the tool |
| Runbooks | Reference the tool in the runbook after the agent has access to it |
Endpoint Safety
Custom tool endpoint URLs must usehttp or https. Duckie blocks local, private, and internal network addresses before making server-side requests.
Authentication
Custom tools can call endpoints with no authentication, manual headers, or OAuth 2.0 client credentials.| Method | Use for | How to configure |
|---|---|---|
| No authentication | Public endpoints or endpoints that only require request parameters | Leave Authentication set to No OAuth and do not add authentication headers |
| Manual headers | API keys, static bearer tokens, Basic auth, and vendor-specific header schemes | Add the required header names and values in Headers |
| OAuth 2.0 client credentials | APIs that issue access tokens from a client ID and client secret | Create or select an OAuth credential in Authentication |
Manual headers
Use manual headers when the API expects a fixed header value. Bearer token:Authorization value.
OAuth 2.0 client credentials
Use OAuth credentials when the API requires Duckie to request an access token before calling the endpoint. To create a credential, click New credential in the custom tool dialog and enter:| Field | Description |
|---|---|
| Name | A reusable label for the credential |
| Token URL | The HTTPS endpoint Duckie calls to request the access token |
| Client ID | The OAuth client ID |
| Client Secret | The OAuth client secret |
| Scope | Optional OAuth scope value |
grant_type=client_credentials, caches valid access tokens, and sends the resolved token as an Authorization header when the custom tool runs. If the token response does not include a token type, Duckie uses Bearer.
The OAuth token URL must use https, cannot contain org variables, and must not resolve to a local, private, or internal network address.
If you select an OAuth credential, remove any manual
Authorization header before saving the custom tool.Parameters
Parameters describe the values Duckie can send to your endpoint.| Type | Use for |
|---|---|
string | IDs, names, email addresses, text values, and other plain strings |
number | Numeric values such as amounts, counts, and limits |
boolean | true or false flags |
object | Structured JSON objects |
array | Lists of values |
| Value source | Behavior |
|---|---|
| AI-generated | The agent supplies the value. Use the description to explain what the parameter should contain. |
| Fixed value | Duckie always sends the configured value. Use this for constants, IDs, flags, or org variables the agent should not infer. |
Template Placeholders
Use{{param}} syntax in URLs and headers when a parameter should be inserted into the request target or header value.
URL with parameter:
POST, PUT, and PATCH requests, non-placeholder parameters are sent in the request body. For GET and DELETE requests, non-placeholder parameters are sent as query parameters.
Org Variables
Org variables can be used in URL paths, URL query strings, headers, and fixed values with{{org.variable_name}} syntax.
Keep the endpoint scheme and hostname literal, such as https://api.example.com. Duckie validates the endpoint host before resolving org variables, then resolves org variables in the path, query string, and headers before making the request.
URL path with org variable:
Write Actions and Approvals
Use Write Action for tools that change external state, such as updating an account, issuing a refund, creating a ticket, or sending a message. Use Requires Approval when a human should approve the tool call before it runs. When approval is enabled, you can notify specific Slack users or a Slack channel. Leave the notification field empty to use the org-wide default.HTTP Timeout
You can set a custom HTTP timeout from 1 to 300 seconds. Leave it blank to use Duckie’s default timeout.Related Pages
Agent Configuration
Enable custom tools for agents
Workflow Actions
Call custom tools from workflows