The new way to API.

Test Mode

Table Of Contents

Test Mode is an advanced feature planned for AgenticAPI v0.4.0, allowing AI agents to simulate actions without committing changes or triggering side effects. Part of the Compute category, Test Mode supports verbs like TEST /action, enabling agents to evaluate outcomes, validate preconditions, and assess risks before execution. This is critical for high-stakes domains (e.g., finance, healthcare) where testing ensures reliability. This document explains Test Mode and provides a planned example of a TEST /action endpoint.

How Test Mode Works #

Test Mode executes a simulated version of an action, returning anticipated results, side effects, and validation checks without altering system state. Key components include:

  • Outcome Prediction: Simulates the action’s result (e.g., a meeting booking ID).
  • Side Effects: Lists potential impacts (e.g., database updates, notifications).
  • Validation Checks: Verifies preconditions (e.g., resource availability, user permissions).
  • Status: Indicates simulation validity (valid, invalid).

The TEST /action endpoint accepts the same payload as the target action, ensuring agents can test real-world scenarios safely.

Example: TEST /action Endpoint #

The following example demonstrates a planned TEST /action endpoint that simulates a SUMMARIZE verb, checking if a document can be summarized without processing it.

Python
from fastapi import FastAPI
from pydantic import BaseModel
from typing import Dict, Any

app = FastAPI()

class TestRequest(BaseModel):
    verb: str  # e.g., SUMMARIZE
    path: str  # e.g., /document
    payload: Dict[str, Any]  # Action-specific parameters

@app.post("/action", openapi_extra={"x-action": "test", "x-category": "compute"})
async def test_action(test: TestRequest):
    if test.verb != "SUMMARIZE" or test.path != "/document":
        return {
            "status": "invalid",
            "error": f"Unsupported verb or path: {test.verb} {test.path}"
        }
    
    # Simulate validation for SUMMARIZE
    document_id = test.payload.get("document_id")
    format = test.payload.get("format", "text")
    max_words = test.payload.get("max_words", 50)
    
    validation_checks = {
        "document_exists": bool(document_id == "doc_001"),  # Mock check
        "format_valid": format in ["text", "bullets"],
        "max_words_valid": isinstance(max_words, int) and 10 <= max_words <= 100
    }
    
    if all(validation_checks.values()):
        return {
            "verb": test.verb,
            "path": test.path,
            "status": "valid",
            "outcome": {
                "summary": "Simulated summary of the document.",
                "title": "Report"
            },
            "side_effects": ["none"],
            "validation_checks": validation_checks
        }
    else:
        return {
            "verb": test.verb,
            "path": test.path,
            "status": "invalid",
            "error": "Validation failed",
            "validation_checks": validation_checks
        }

Request:

Bash
curl -X POST http://localhost:8000/action -H "Content-Type: application/json" -d '{
  "verb": "SUMMARIZE",
  "path": "/document",
  "payload": {
    "document_id": "doc_001",
    "format": "text",
    "max_words": 20
  }
}'

Response (Valid):

JSON
{
  "verb": "SUMMARIZE",
  "path": "/document",
  "status": "valid",
  "outcome": {
    "summary": "Simulated summary of the document.",
    "title": "Report"
  },
  "side_effects": ["none"],
  "validation_checks": {
    "document_exists": true,
    "format_valid": true,
    "max_words_valid": true
  }
}

Request (Invalid):

Bash
curl -X POST http://localhost:8000/action -H "Content-Type: application/json" -d '{
  "verb": "SUMMARIZE",
  "path": "/document",
  "payload": {
    "document_id": "doc_999",
    "format": "invalid",
    "max_words": 5
  }
}'

Response (Invalid):

JSON
{
  "verb": "SUMMARIZE",
  "path": "/document",
  "status": "invalid",
  "error": "Validation failed",
  "validation_checks": {
    "document_exists": false,
    "format_valid": false,
    "max_words_valid": false
  }
}
  • TestRequest: Specifies the verb, path, and payload to simulate.
  • Validation Checks: Verifies preconditions (e.g., document existence, valid format).
  • Outcome: Predicts the result without executing the action.
  • Side Effects: Indicates no state changes in Test Mode.
  • Planned for v0.4.0: Full implementation with support for all verbs.

Benefits #

  • Risk Reduction: Simulate actions to avoid unintended consequences.
  • Agent Confidence: Validate preconditions before execution.
  • Debugging: Identify issues in complex workflows.
  • High-Stakes Use Cases: Essential for finance, healthcare, or critical systems.

Best Practices #

  • Test All Verbs: Ensure TEST /action supports all action verbs in your API.
  • Validate Thoroughly: Include comprehensive checks for preconditions.
  • Document Side Effects: Use x-side-effects in OpenAPI to clarify impacts.
  • Plan for v0.4.0: Prepare agents to leverage Test Mode when available.

Next Steps #

What are your feelings
Updated on May 29, 2025