HTTP Call (infrastructure)

What it is

HTTP Call is the infrastructure that lets an agent query or trigger an API through a custom HTTP tool. You do not add this item from the native tools catalog: you create an organization tool, configure the endpoint, and then link it to the agents that should use it.

The current type is org_http_tool. The runtime also keeps compatibility with legacy http_api records, but this internal distinction does not change the configuration flow.

Where to create and link it

From the side menu, open Tools → Active. In Custom Tools, select New Tool, then HTTP / API Tool. Creating or editing the base configuration requires Edit tools (tools.write); deleting requires Delete tools (tools.delete).

After saving, open the agent and use Tools → Add Tool → Other Tools to link it. A configuration created on the Tools page belongs to the organization and can be reused by multiple agents. Changing the base configuration immediately affects every linked agent; deletion is blocked while links still exist.

The agent editor can adjust parameter values for that agent only: the model can provide a value, you can fix it manually, or you can omit an optional parameter. Endpoint, authentication, and schema remain managed on the Tools page.

Caution

The agent selector does not yet follow every granular permission: it may show a link that the backend will reject or hide New Tool from an authorized custom role. If this happens, review agents.write and tools.write, then create the base configuration under Tools.

See every editor field in Custom HTTP Tools.

What the model receives

The model sees only the contract it needs to choose and assemble the call:

• the technical name, unique within the organization;
• the description of the tool’s purpose;
• the JSON Schema for the parameters it may provide.

Use a specific technical name, task-oriented descriptions, and unambiguous parameters. Values fixed or omitted at agent level are removed from the schema exposed to the model. The authentication token never enters the prompt or tool result.

How the request is built

The executor accepts GET, POST, PUT, PATCH, and DELETE. It replaces :key path parameters, appends query parameters, and injects authentication and headers on the server.

• For GET, values already present in the URL take precedence, followed by configured parameters and additional model arguments.
• For other methods, a JSON template can use model arguments. Fields whose placeholder was not resolved are removed when the template is valid JSON. Without a template, additional arguments form the JSON body.
• Send conversation metadata adds data such as conversation, external contact, agent, and model only to JSON bodies for methods other than GET. Keys already written in the template take precedence.
• Provide lead identity to context changes model context; it does not automatically append that data to the request.

To mark parameters as required, use JSON Schema in advanced mode. The current visual builder creates optional parameters and has no required control.

Security and execution limits

The final URL is validated before the call. Only http and https are accepted, and local, private, reserved, and cloud metadata addresses are blocked. Even so, treat the endpoint as a trusted part of your architecture: send only necessary data, limit credential privileges, and rotate credentials regularly.

The UI keeps the secret as a write-only field, and the executor reads it on the server without exposing it to the model. However, in the audited implementation, the value is written directly to the secret column even though the UI says it is encrypted. Until the product is corrected, do not treat this storage as an encrypted vault at rest.

Each call has an effective limit of 30 seconds, even if the form accepts a higher value. The response body is limited to 1 MiB. Valid JSON responses are delivered as structured data; other responses arrive as text. On an HTTP error, the agent receives the status and only the beginning of the error body.

Caution

When a response exceeds 1 MiB, the runtime cuts it without telling the model that truncation occurred. Prefer paginated endpoints and small responses to prevent decisions based on incomplete data.

Identical calls are not repeated in the same turn, and up to three HTTP tools can run in parallel in one batch.

Testing and publishing

The Test tool panel sends a real request to the endpoint and displays status, duration, and body. Use a test credential and environment when the operation can create, update, or delete data. The tool appears active after it is saved; a successful test does not persist a validation badge and is not required for activation.

The current test does not perfectly reproduce agent execution: configured query parameters and missing body placeholders may be assembled differently, and conversation metadata is mocked. Therefore, also validate the saved version with a test agent and inspect the destination system to confirm which data arrived.

Saving the configuration, secret, and agent synchronization happens in separate steps. If one step fails, reload the tool before retrying, confirm the endpoint and authentication, and check that a duplicate was not created.

When to use it

Use an HTTP tool when the agent must access a system without a ready integration: your own API, an internal CRM or ERP, a public service, or an automation webhook. Do not use a generic call when a native tool or existing integration already provides a narrower, more observable, and easier-to-maintain contract.