Skip to main content
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.

​
Create a Custom Tool

1

Navigate to Tools

Go to Build → Tools, then open the Custom Tools tab.
2

Create the tool

Click Tool to open the custom tool dialog.
3

Add basic details

Enter a name and description. The description helps the agent understand when to use the tool.
4

Configure the endpoint

Choose a method and enter the endpoint URL.Supported methods are GET, POST, PUT, PATCH, and DELETE.
5

Choose authentication

Select an OAuth credential for OAuth 2.0 client credentials, or leave No OAuth and add authentication headers manually.
6

Add headers

Add any non-OAuth headers the endpoint requires, such as API keys, vendor headers, content type headers, or request-specific values the agent should generate.
7

Define parameters

Add the inputs the tool accepts. Parameters can be AI-generated or fixed values.
8

Test the tool

Use Test Tool with sample values before enabling the tool for an agent or assistant.

​
Enable a Custom Tool

After creating a custom tool, choose where it can be used:
SurfaceHow to use the tool
AgentsOpen the agent’s tool access settings and enable the custom tool
Internal assistantOpen Settings > Assistant and enable the custom tool
WorkflowsAdd an Action node, open the Custom tab, and select the tool
RunbooksReference the tool in the runbook after the agent has access to it

​
Endpoint Safety

Custom tool endpoint URLs must use http or https. Duckie blocks local, private, and internal network addresses before making server-side requests.

​
Authentication

Custom tools can call endpoints with no authentication, fixed headers, AI-generated headers, or OAuth 2.0 client credentials.
MethodUse forHow to configure
No authenticationPublic endpoints or endpoints that only require request parametersLeave Authentication set to No OAuth and do not add authentication headers
Fixed headersAPI keys, static bearer tokens, Basic auth, content type headers, and other values that should be sent the same way each timeAdd the header in Headers, choose Fixed value, and enter the value Duckie should send
AI-generated headersHeader values that depend on the current request and should be supplied by the agent when the tool runsAdd the header in Headers, choose AI-generated, describe the expected value, and mark it required if the endpoint needs it
OAuth 2.0 client credentialsAPIs that issue access tokens from a client ID and client secretCreate or select an OAuth credential in Authentication

​
Header value sources

Each custom header can use one of two value sources:
Value sourceBehavior
Fixed valueDuckie sends the configured value whenever the tool runs. Fixed headers support parameter placeholders and org variables.
AI-generatedThe agent supplies the header value when the tool runs. Use the description to explain exactly what the header should contain.
Use fixed headers when the API expects a constant value. Bearer token: 
Authorization: Bearer {{org.api_key}}
API key header: 
X-API-Key: {{org.api_key}}
Basic auth: 
Authorization: Basic <base64-encoded-username-and-password>
For Basic auth, enter the final encoded Authorization value. Use AI-generated headers when the header value should be inferred from the current request instead of stored in the tool configuration or sent as a body/query parameter. Request-specific routing header: 
X-Customer-Tier: enterprise
When a tool has AI-generated headers, Duckie exposes those headers to the agent as api_headers, sends only the header names configured on the tool, and merges the generated values into the outbound request. Do not add a normal parameter named api_headers to a custom tool that also has AI-generated headers; that name is reserved for header values.

​
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:
FieldDescription
NameA reusable label for the credential
Token URLThe HTTPS endpoint Duckie calls to request the access token
Client IDThe OAuth client ID
Client SecretThe OAuth client secret
ScopeOptional OAuth scope value
Duckie requests tokens with 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.
TypeUse for
stringIDs, names, email addresses, text values, and other plain strings
numberNumeric values such as amounts, counts, and limits
booleantrue or false flags
objectStructured JSON objects
arrayLists of values
Each parameter can use one of two value sources:
Value sourceBehavior
AI-generatedThe agent supplies the value. Use the description to explain what the parameter should contain.
Fixed valueDuckie always sends the configured value. Use this for constants, IDs, flags, org variables, or run metadata values the agent should not infer.
Parameters can be required or optional. Parameters referenced in endpoint or header templates are automatically required.

​
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: 
https://api.example.com/orders/{{order_id}}
Header with parameter: 
X-Customer-Email: {{email}}
Duckie automatically creates required parameters for placeholders it finds in the URL or headers. For 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: 
https://api.example.com/{{org.region}}/orders/{{order_id}}
Header with org variable: 
Authorization: Bearer {{org.api_key}}
Fixed parameter value with org variable: 
{{org.default_team_id}}
When using an org variable as a fixed parameter value, make the whole value the org variable reference. Duckie does not expand org variables embedded inside longer AI-generated parameter values.

​
Context Variables

Context variables let a custom tool use values from the run’s metadata. Use {{context.variable_name}} as the full fixed value for a parameter. For example, if a run has metadata with a phone field, set the custom tool parameter to: 
{{context.phone}}
Duckie resolves the fixed value before calling the tool, so the agent does not need to generate that parameter. Context variables also support nested metadata paths: 
{{context.customer.phone}}
To use a context variable in a URL path, query string, or header, route it through a fixed parameter and reference that parameter with normal {{param}} placeholders. URL path using a context-backed parameter: 
Endpoint: https://api.example.com/customers/{{phone}}/orders
Parameter phone fixed value: {{context.phone}}
Header using a context-backed parameter: 
Header: X-Customer-Phone: {{phone}}
Parameter phone fixed value: {{context.phone}}
When using a context variable as a fixed parameter value, make the whole value the context variable reference. Duckie does not expand context variables embedded inside longer AI-generated parameter values.

​
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.

Agent Configuration

Enable custom tools for agents

Workflow Actions

Call custom tools from workflows

Duckie as an External Subagent

Send a focused Duckie agent’s result back to a customer-owned orchestrator.