Custom HTTP Tools

Custom HTTP tools let an agent query or trigger a REST API, such as an n8n or Make webhook, a CRM, an ERP, or your own service. The base configuration belongs to the organization; each agent receives only a link and, when needed, parameter overrides.

To understand how the call runs, also see HTTP Call (infrastructure).

Before you begin

Confirm four points outside SquadOS:

1. the public endpoint method and URL;
2. the exact path, query, headers, and body format;
3. authentication and a credential with the least privilege possible;
4. whether the call only reads data or produces effects such as creating, updating, or deleting records.

Use a test endpoint and credential during configuration. The test panel sends a real request and can produce the same external effect as a call made by the agent.

Create the tool

1. From the side menu, open Tools → Active.
2. In Custom Tools, select New Tool.
3. In the New Tool picker, choose HTTP / API Tool. The other option creates an MCP Server.
4. Complete the Create HTTP tool drawer and select Create tool.

Creating or editing requires Edit tools (tools.write). Deleting requires Delete tools (tools.delete). Saved tools appear Active without requiring a successful test.

Identity and endpoint

Field	Current contract
Tool name	Required. Friendly name shown in the panel; up to 100 characters. The model does not receive this name.
Technical name (used by the AI)	Generated from the friendly name with lowercase letters, numbers, and _. Select Customize to change it. It is unique within the organization and is shown to the model.
Description	Optional, up to 500 characters. State what the tool does, when it should be called, and when it should not. The model uses this text to choose the tool.
Method	GET, POST, PUT, PATCH, or DELETE.
Endpoint URL	Required, up to 2,048 characters. Use :key for a path parameter, for example https://api.example.com/users/:id.

Saving only checks that name and URL are not empty; it does not prove that the URL is valid, public, or reachable. Use Test tool before linking the configuration to an agent.

Caution

The runtime accepts only http and https and blocks localhost, private and reserved networks, and cloud metadata endpoints. Correct a URL rejected in testing or conversation; do not try to bypass the protection.

Authentication

Type	Header sent
None	No authentication header.
Bearer Token	Authorization: Bearer YOUR_TOKEN.
API Key (Header)	The configured header, or X-API-Key when its name is empty; the value is the secret.
Custom header	The configured header, or Authorization; it may add a prefix such as Token.

When editing, the secret is a write-only field: leave it empty to preserve the current value, or fill it to replace the value. The executor retrieves the credential on the server and never includes it in the prompt or result delivered to the model.

Danger

Although the current UI says the secret is encrypted, the audited implementation writes the value directly to the secret column. Use dedicated, restricted credentials, rotate them regularly, and do not treat this storage as an encrypted vault at rest.

Selecting None prevents the secret from being used, but does not delete the stored value. There is no separate action to remove only the credential: revoke it in the destination service to guarantee invalidation; deleting the tool removes its associated secret record.

Parameters the model can send

Parameters form the JSON Schema shown to the model. Each visual-builder row provides:

• Name;
• Type: string, number, boolean, or object;
• Description.

Select Add to create another row. The current visual builder has no Required control; every new row is optional. To define required, an enum, an array, a nested object, or other constraints, use Edit as JSON Schema (advanced). The text accepts up to 64,000 characters and is validated only as syntactically valid JSON when saved.

Example schema with one required argument:

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "Concise summary of the customer's problem"
    }
  },
  "required": ["text"]
}

Danger

The current editor does not preserve advanced schemas when you reopen the tool: it returns to the visual builder and retains only name, type, description, and the required list. Saving again can remove enums, arrays, nested structures, and other constraints. Keep the source schema outside SquadOS and do not re-edit a tool that depends on those features without checking the complete contract.

JSON body

The JSON body block appears under Advanced only for methods other than GET. It accepts up to 64,000 characters and combines fixed values with {{parameter_name}} placeholders.

{"message":"{{text}}","channel":"web","priority":"high"}

If the model sends text: "Customer cannot sign in", the body becomes:

{"message":"Customer cannot sign in","channel":"web","priority":"high"}

When the template is valid JSON, fields whose placeholder received no value are removed. When the resulting template is not valid JSON, the executor sends the resulting text without converting or validating it. Without a template, model arguments form a simple JSON object.

Advanced options

Open Advanced to configure:

Custom headers

They are sent with every request. The executor starts with Content-Type: application/json, applies custom headers, then injects the authentication header. Therefore, configured authentication wins when it uses the same header name.

Path parameters

Each row has Key, Default value, and AI provides. The key replaces :key in the URL, and its value is URL-encoded. When AI provides is enabled, the parameter enters the agent contract as required; when disabled, the fixed value is used.

Query parameters

They also use Key, Default value, and AI provides. For GET, values already written in the URL take precedence, followed by configured rows and then additional model arguments not already present in the query.

Timeout

The field accepts 1,000 to 300,000 ms, but runtime and test apply an effective ceiling of 30,000 ms (30 seconds). Do not configure a higher value expecting the call to wait longer.

Send conversation metadata

Adds conversation_id, conversation_title, external_contact, agent_id, model_used, ai_enabled, and external_user_id. This happens only for methods other than GET when the final body is a valid JSON object. Keys already defined in the body take precedence.

Provide lead identity to context

Makes the contact’s external identifier and name available to the model so it can fill arguments. This option does not automatically append the data to the endpoint. Enable it only when the tool’s purpose requires identifying the lead.

Caution

Closing the drawer after changing only the schema, body, headers, path/query, timeout, or either context control may discard the change without showing Discard changes?. Save explicitly before leaving.

Test the tool

The Test tool panel remains at the end of the drawer.

1. Fill in the test values.
2. Select Run test.
3. Review the displayed HTTP status, duration, and body.
4. Inspect the destination system to verify URL, headers, body, and any effect created.

The test uses the credential you entered or, while editing, the stored secret. It sends a real request but does not perfectly reproduce runtime execution:

• it treats every argument as a string of up to 100 characters, even when the schema declares number, boolean, or object;
• it may build configured query parameters differently;
• it substitutes missing body placeholders differently;
• it uses mocked conversation metadata;
• it receives response headers and a truncation indicator, but the panel does not display them.

A green test does not persist a validation state and does not guarantee that the agent call will be identical. Also run a controlled conversation with a test agent.

Link and configure it on an agent

1. Open Agents → your agent → Tools.
2. Select Add Tool.
3. Under Other Tools, choose the HTTP tool.
4. Open the linked tool to configure each parameter as a value decided by the AI, a manual value, or Don’t send when optional.
5. Save and test a new conversation.

Path parameters provided by the AI are required. Optional parameters may be omitted. The Base configuration is managed in Admin > Tools link returns to the organization editor.

Caution

The agent selector does not yet follow every granular permission. A user may see a link the backend will reject; a custom role with tools.write may also miss New Tool because that shortcut still depends on the legacy Admin role. Create the base configuration under Tools and also check agents.write.

Edit, recover, and delete

When editing a linked tool, SquadOS shows This tool is in use and lists how many agents will be affected. A base configuration change applies immediately to all of them.

Configuration, link synchronization, and secret are saved in separate steps. If an error appears, reload the list before retrying: confirm what was actually persisted and look for a duplicate tool. A late failure can leave only part of the change applied.

To delete, first remove the tool from every agent; the foreign key blocks deletion while links exist. Deleting the tool is irreversible and also removes its secret record.

Limits that affect the agent response

• each call ends after no more than 30 seconds;
• the response body is read up to 1 MiB;
• the model is not told when that body was truncated;
• valid JSON responses become structured data; other responses arrive as text;
• for non-2xx status, the agent receives the status and only the first 500 characters of the error body;
• an identical call is not repeated in the same turn;
• up to three HTTP calls may run in parallel in one batch.

Prefer paginated endpoints, small responses, and idempotent operations. For actions with external effects, accept an idempotency key and log the conversation or operation identifier in the destination system.

Publishing checklist

• The technical name describes one action, and the description explains when to call it.
• The schema contains only arguments the model should decide.
• Sensitive and constant values stay on the server or as fixed values, never in the prompt.
• The credential has minimal scope and can be revoked without affecting other systems.
• Path, query, headers, and body were confirmed in the destination system.
• 4xx, 5xx, timeout, and empty-response behavior were tested.
• The endpoint is idempotent or protects against repetition across turns.
• The saved version was validated with a test agent before reaching real conversations.