FIfish
Agent Tools

Create Tool

Changed on

Create a workspace tool. tool_type: webhook calls your HTTP endpoint during conversations; tool_type: client is executed by your own frontend through the SDK (no URL). Describe the call with parameters (a JSON Schema object, checked at call time under parameter_mode: strict) or the older arguments list (every argument a required string, unchecked). Attach it to agents via the agent config's tools.tool_ids. Credential headers (authorization_bearer / authorization_basic) are write-only and read back as has_secret.

post/v1/agent/tools

Request

  • Base URL
    https://api.fish.audio
  • URL
    https://api.fish.audio/v1/agent/tools
  • Auth
    HTTP bearer

Request body

namestring required
descriptionstring
tool_type'webhook' | 'client'
parametersobject nullable

Call parameters as a JSON Schema object (draft 2020-12): type: object (filled in when omitted), properties, required. Standard meaning throughout: required means the key must be present, type: ["string", "null"] allows null, minLength: 1 makes a string non-empty, enum and pattern constrain the value, default fills a key the model left out. Mutually exclusive with arguments in one request. A tool created with parameters starts in parameter_mode: strict.

parameter_mode'legacy' | 'strict' nullable

Whether the agent runtime checks each call's arguments against parameters before running the tool. legacy (the default for tools created with arguments, and every tool from before this field existed): no check, the model's arguments run as sent. strict (the default for tools created with parameters): a call that does not satisfy the schema is refused and the model is told to ask the caller for the missing information, and the LLM provider's constrained decoding is turned on where the model supports it (OpenAI models and a custom OpenAI-compatible endpoint receive the tool with strict: true, Gemini on the platform's native channel runs validated function calling). Changing parameters never changes the mode, and the mode can be changed on its own.

method'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
urlstring
content_typestring
body_templatestring

Request body sent for non-GET calls. {{argument}}, {{system.*}} and custom session variable placeholders are filled in at call time; a missing value becomes empty. When the body's content type is JSON (the default application/json, any +json type, or a Content-Type header saying so), a placeholder inside a JSON string, such as {"note": "{{note}}"}, is JSON-escaped, so quotes, backslashes and newlines in the value keep the body valid JSON. A placeholder outside a string, such as {"count": {{count}}}, is inserted as is. Other content types are filled in as is.

timeout_secondsinteger
error_handling'passthrough' | 'hide'
expects_responseboolean
execution_mode'blocking' | 'fire_and_forget' | 'background'

Response

Document created, URL follows

tool_idstring required
workspace_idstring required
namestring required
descriptionstring
tool_type'webhook' | 'client' required
method'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' required
urlstring required
used_byinteger

How many agents reference this tool in their draft configuration.

created_atstring date-time required
updated_atstring date-time required
parametersobject required

Call parameters as a JSON Schema object (draft 2020-12): type: object (filled in when omitted), properties, required. Standard meaning throughout: required means the key must be present, type: ["string", "null"] allows null, minLength: 1 makes a string non-empty, enum and pattern constrain the value, default fills a key the model left out. Mutually exclusive with arguments in one request. A tool created with parameters starts in parameter_mode: strict.

parameter_mode'legacy' | 'strict'

Whether the agent runtime checks each call's arguments against parameters before running the tool. legacy (the default for tools created with arguments, and every tool from before this field existed): no check, the model's arguments run as sent. strict (the default for tools created with parameters): a call that does not satisfy the schema is refused and the model is told to ask the caller for the missing information, and the LLM provider's constrained decoding is turned on where the model supports it (OpenAI models and a custom OpenAI-compatible endpoint receive the tool with strict: true, Gemini on the platform's native channel runs validated function calling). Changing parameters never changes the mode, and the mode can be changed on its own.

content_typestring required
body_templatestring
timeout_secondsinteger required
error_handling'passthrough' | 'hide' required
expects_responseboolean
execution_mode'blocking' | 'fire_and_forget' | 'background'

Changes