Tool Testing

Test context graph tools without starting a phone call. Resolve available tools, execute world tools, and understand test-mode persistence.

The tool testing endpoints let you resolve all context graph tools (world tools, skills, integrations) for a service and execute world tools in isolation, without making a phone call. Skills and integrations are tested through their own dedicated test/invoke endpoints. This is useful during development for verifying tool behavior, debugging input/output schemas, and validating write operations before wiring tools into a live conversation flow.

Admin/owner only. Tool testing requires the tools:test scope, which is restricted to admin and owner roles.

Test-Mode Behavior

Tool testing changes the execution context, but it is not a universal sandbox. A non-dry-run test can persist data, and not every handler applies dry_run in the same way. Use test records and non-production credentials for any operation that could affect an external system.

• Source tagging: supported writes are tagged source="tool_test". Platform pipelines can use that provenance to exclude test data from production processing.
• Persistent tests: with dry_run=false, write tools can create test-tagged records.
• Dry runs: writer-backed world tools are simulated when dry_run=true. Surface handlers currently execute their normal test path, so do not assume that the flag prevents every write.
• Surface delivery: the platform blocks outbound delivery for surfaces created with the tool-test source.

Resolve Available Tools

Retrieve the full list of tools available for a given service, including their input schemas, types, tiers, and write classification.

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"
}

Execute a Tool

Execute a single tool in isolation with custom input parameters.

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"
}

World tools only. This endpoint executes world_tool tools exclusively. The skill, integration, platform function (fn_*), and workspace data query (wsq_*) tool families use the dedicated operations below. Passing a non-world_tool type returns a validation error pointing at the appropriate operation.

Test a Skill

Test a skill

post

Execute a skill in isolation with the given input.

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

skill_idstring · uuidRequired

Body

Responses

200

Successful Response

application/json

resultstringRequired

Final result text produced by the skill

duration_msnumberRequired

Total execution time in milliseconds

input_tokensintegerRequired

Number of input tokens consumed

output_tokensintegerRequired

Number of output tokens generated

cached_tokensintegerRequired

Number of tokens served from cache

roundsintegerRequired

Number of agent reasoning rounds executed

errorstring · nullableOptional

Error message if the skill execution failed

401

Missing or invalid API key.

403

Insufficient permissions.

404

Skill not found.

422

Validation Error

application/json

post/v1/{workspace_id}/skills/{skill_id}/test

POST /v1/{workspace_id}/skills/{skill_id}/test HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 103

{
  "input": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "static_tool_mocks": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

{
  "result": "text",
  "duration_ms": 1,
  "input_tokens": 1,
  "output_tokens": 1,
  "cached_tokens": 1,
  "rounds": 1,
  "sub_tool_logs": [
    {
      "tool_name": "text",
      "input": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "output": "text",
      "duration_ms": 1,
      "succeeded": true,
      "round": 1
    }
  ],
  "error": "text"
}

Test an Integration Endpoint

Integration endpoints are addressed by integration and endpoint ID, not name.

Test an integration endpoint

post

Execute an integration endpoint with test parameters and return the full response pipeline breakdown. Requires Integration.view permission.

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

integration_idstring · uuidRequired

endpoint_idstring · uuidRequired

Body

Inputs to POST /{integration_id}/endpoints/{endpoint_id}/test.

Responses

200

Successful Response

application/json

Full breadcrumb returned by the test handler.

status_codeinteger · nullableOptional

HTTP status code from the upstream call.

duration_msnumberOptional

Request duration in milliseconds.

Default: 0

retriesintegerOptional

Number of retry attempts.

Default: 0

raw_responseanyOptional

Raw response body from the upstream call.

renderedstring · nullableOptional

Response after Jinja response_template rendering, pre-truncation.

final_resultstring · nullableOptional

Final processed result (rendered + truncated to max_response_length).

errorstring · nullableOptional

Error message if the request failed.

artifact_errorstring · nullableOptional

Safe validation summary when client output is enabled but cannot be emitted.

401

Missing or invalid API key.

403

Insufficient permissions.

404

Integration or endpoint not found.

422

Validation Error

application/json

post/v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id}/test

POST /v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id}/test HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 102

{
  "params": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "auth_params": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "status_code": 1,
  "duration_ms": 0,
  "retries": 0,
  "raw_response": null,
  "rendered": "text",
  "final_result": "text",
  "error": "text",
  "artifact": {
    "type": "text",
    "schema_version": "text",
    "payload": {
      "ANY_ADDITIONAL_PROPERTY": true
    }
  },
  "artifact_error": "text"
}

Invoke a Platform Function

Execute a registered platform function

post

Execute a registered function and return its rows.

Bound parameters are validated against the stored schema; ws_id is auto-injected from the request context. Returns the executor's shaped response (rows for returns=table, scalar value for returns=scalar).

Permissions: Workspace.view (read role and above). Read-only keys are intentionally allowed — invocation runs a stored, pre-validated SELECT against catalogs the workspace SP already has SELECT on; the gate on what can run is the deploy-time validator (read-only invariant), not the per-call permission.

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

function_namestringRequired

Body

Invoke a registered function with caller-supplied args.

Responses

200

Successful Response

application/json

resultanyOptional

duration_msnumberOptionalDefault: 0

row_countintegerOptionalDefault: 0

404

Function not found

422

Bind validation failure

429

Rate limited

post/v1/{workspace_id}/functions/{function_name}/invoke

POST /v1/{workspace_id}/functions/{function_name}/invoke HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "input": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "result": null,
  "duration_ms": 0,
  "row_count": 0
}

Test a Platform Function

Test invoke + persist last_test_* telemetry on the row

post

Test invoke — same as invoke + persists last_test_* on the row.

Returns 200 with status="fail" + populated error on execution failure (instead of a 5xx) so the DC has a single happy-path rendering.

Permissions: admin, owner.

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

function_namestringRequired

Body

Invoke a registered function with caller-supplied args.

Responses

200

Successful Response

application/json

Response shape for POST /v1/{ws}/functions/{name}/test.

Structural superset of :class:InvokeResponse. Adds status and error so the DC can render the executor's failure detail inline rather than a generic "Invocation failed." The underlying invoke uses the same path; status / error are filled in by service.test after catching any HTTPException (503) from the executor, so the route never bubbles a 5xx for a logical SQL failure — it's still a 200 with status=fail so the caller can show the message.

Invariant (enforced by :func:_check_error_when_fail): status == "fail" → error is not None and len(error) > 0.

resultanyOptional

duration_msnumberOptionalDefault: 0

row_countintegerOptionalDefault: 0

statusstringOptionalDefault: pass

errorstring · max: 2000 · nullableOptional

test_duration_msinteger · nullableOptional

404

Function not found

422

Validation Error

application/json

429

Rate limited

post/v1/{workspace_id}/functions/{function_name}/test

POST /v1/{workspace_id}/functions/{function_name}/test HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "input": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "result": null,
  "duration_ms": 0,
  "row_count": 0,
  "status": "pass",
  "error": "text",
  "test_duration_ms": 1
}

Invoke a Workspace Data Query

Workspace data queries are addressed by query ID, not name. See Workspace Data Queries for deployment and runtime guidance.

Invoke Workspace Data Query

post

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

query_idstring · uuidRequired

Body

Responses

200

Successful Response

application/json

duration_msnumberOptionalDefault: 0

row_countintegerOptionalDefault: 0

404

Workspace data query not found

422

Validation Error

application/json

503

Execution failed

post/v1/{workspace_id}/data_queries/{query_id}/invoke

POST /v1/{workspace_id}/data_queries/{query_id}/invoke HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "input": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "result": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "duration_ms": 0,
  "row_count": 0
}

Rate limited. Tool execute is subject to write rate limits. Use resolve to inspect tools before executing.