AgenticAPI responses are designed to provide clear outcomes and support AI agent decision-making. Each response follows a standardized structure, ensuring execution clarity and adaptability across action verbs. This document details the response structure, including status, result, and next_action fields, with examples for common verbs.

Response Structure #

Responses include the following key components:

• status: Indicates the outcome of the action (e.g., completed, failed).
• result: Contains the action-specific output, such as a summary or notification status.
• next_action (optional): Suggests a follow-up action (e.g., PUBLISH /summary).
• output_format: Specifies the response format (e.g., json, text), based on the request’s execution hint.
• confidence (optional): A score (0.0–1.0) reflecting the action’s certainty, useful for agent reasoning.

The structure is consistent across verbs, with the result field varying by action.

Example Responses #

Below are example responses for two common verbs, illustrating the structure.

SUMMARIZE Response #

The SUMMARIZE verb generates a document summary, with the result containing the summary text.

{
  "status": "completed",
  "result": {
    "summary": "Report highlights revenue growth and cost reduction.",
    "title": "Annual Report"
  },
  "output_format": "json",
  "next_action": "PUBLISH /summary",
  "confidence": 0.92
}

• status: completed indicates successful summarization.
• result: Contains the summary and title.
• next_action: Suggests publishing the summary.
• output_format: Matches the request’s json preference.
• confidence: Reflects the summarization’s reliability.

FETCH Response #

The FETCH verb retrieves a document, with the result containing the content.

{
  "status": "completed",
  "result": {
    "content": "This is the document content.",
    "title": "Sample Document"
  },
  "output_format": "json"
}

• status: completed indicates successful retrieval.
• result: Includes the document’s content and title.
• output_format: JSON as requested.

Error Responses #

If an action fails, the response includes an error message:

{
  "status": "failed",
  "error": "Document doc_001 not found",
  "output_format": "json"
}

Best Practices #

• Check Status: Agents should handle failed status with retries or fallbacks.
• Use Next Action: Follow suggested actions for workflow continuation.
• Validate Confidence: Consider confidence for critical decisions (planned for future versions).

Next Steps #

• Explore Payloads and Parameters for input details.
• Learn about ACTION Taxonomy for verb categories.
• Try Chaining Actions to combine verbs.