Sign in
Tools

Test Lambda tool

Tests an existing Lambda tool by executing it with test inputs. Use this to verify a function works correctly before agents use it. Optionally supply a test_context with stand-in agent metadata, secrets, and session metadata. The $refs in the tool's stored tool_configurations resolve against these values. The function runs in a secure sandbox environment with the same constraints as production.

post/v2/tools/{tool_id}/test

Path parameters

tool_idstring required
Example:tol_python_function_123

The unique identifier of the Lambda tool to test.

Headers

Request-Timeoutinteger

The platform makes a best effort to complete the request in the specified seconds, or it times out.

Request-Timeout-Millisinteger

The platform makes a best effort to complete the request in the specified milliseconds, or it times out.

Request body

inputobject required

The input parameters to pass to the function. Must match the tool's input schema.

timeout_secondsinteger

Maximum execution time in seconds for this test. Overrides execution_configuration if specified. When omitted, the tool's stored execution_configuration timeout applies in full — up to 21600 seconds — and a tool with none runs at 30 seconds. A budget longer than 300 seconds requires stream_response to be true; a non-streaming request with a larger budget is rejected.

stream_responseboolean

When true, the response is streamed as Server-sent Events. While the test runs the platform sends zero or more heartbeat events, then exactly one terminal result event carrying the same object the non-streaming response returns. A platform failure after the stream has started closes the connection without a result.

Example request

{
  "input": {
    "number": 42,
    "text": "Hello, world!"
  },
  "timeout_seconds": 10,
  "test_context": {
    "agent": {
      "metadata": {
        "ticket_api_base": "https://tickets.example.com/api/v1/"
      },
      "secrets": {
        "ticket_api_token": "test-token"
      }
    },
    "session": {
      "metadata": {
        "tenant_corpus": "kb"
      }
    }
  }
}

Response

The test execution results, or the streamed events when stream_response is true.

OR

Example response

{
  "type": "success",
  "output": {
    "result": 1764,
    "message": "Computed successfully"
  },
  "latency_millis": 125,
  "memory_used_mb": 32,
  "validation_results": {
    "input_valid": true,
    "output_valid": true,
    "validation_errors": [
      "Output missing required field 'result'"
    ]
  }
}

Changes

Changed in 1 of the 13 revisions of this API.3

  • 05ae305c8d843See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      the request property's max was increased from 300.00 to 21600.00

      request-property-max-increased

    • ○

      added the media type text/event-stream for the response with the status

      response-media-type-added

    This revision also has 9 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog