Tool Testing

Execute a tool in test mode

post

Run an HSM tool outside a live session for testing.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

tool_typestring · max: 64Required

world_tool — other tool families use their dedicated endpoints

tool_namestring · min: 1 · max: 256Required

Fully qualified tool name

service_idstring · uuidRequired

Service ID that owns the HSM

entity_idstring · uuid · nullableOptional

Optional entity ID for context

dry_runbooleanOptional

If true, write tools are simulated without persistence

Default: false

Responses

200

Successful Response

application/json

resultanyOptional

duration_msnumberOptionalDefault: 0

dry_runbooleanOptionalDefault: false

sourcestringOptionalDefault: tool_test

tool_typestringOptionalDefault: ""

tierstringOptionalDefault: world

is_writebooleanOptionalDefault: false

blocked_side_effectsstring[]Optional

errorstring · nullableOptional

401

Missing or invalid credentials.

403

Insufficient permissions.

422

Invalid request body.

503

Voice agent service unavailable.

post/v1/{workspace_id}/tools/execute

POST /v1/{workspace_id}/tools/execute HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 212

{
  "tool_type": "text",
  "tool_name": "text",
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "input_params": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "dry_run": false
}

{
  "result": null,
  "duration_ms": 0,
  "dry_run": false,
  "source": "tool_test",
  "tool_type": "",
  "tier": "world",
  "is_write": false,
  "sub_tool_logs": [
    {
      "tool_name": "",
      "input": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "output": "",
      "duration_ms": 0,
      "succeeded": true
    }
  ],
  "blocked_side_effects": [
    "text"
  ],
  "error": "text"
}

Resolve tools for a service

get

List all tools available for a service's HSM with metadata.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

service_idstring · uuidRequired

Responses

200

Successful Response

application/json

service_idstring · uuidRequired

workspace_idstring · uuidRequired

401

Missing or invalid credentials.

403

Insufficient permissions.

422

Validation Error

application/json

503

Voice agent service unavailable.

get/v1/{workspace_id}/services/{service_id}/tools/resolve

GET /v1/{workspace_id}/services/{service_id}/tools/resolve HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "tools": [
    {
      "tool_name": "text",
      "tool_type": "text",
      "description": "",
      "input_schema": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "states": [
        "text"
      ],
      "tier": "world",
      "is_write": false,
      "additional_instructions": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000"
}

List built-in tool catalog

get

List the platform's built-in world + surface tools (workspace-independent).

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Responses

200

Successful Response

application/json

401

Missing or invalid credentials.

403

Insufficient permissions.

503

Voice agent service unavailable.

get/v1/{workspace_id}/tools/catalog

GET /v1/{workspace_id}/tools/catalog HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "tools": [
    {
      "tool_name": "text",
      "tool_type": "text",
      "description": "",
      "input_schema": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "states": [
        "text"
      ],
      "tier": "world",
      "is_write": false,
      "additional_instructions": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}