AgenticAPI’s action-oriented design relies on well-defined input payloads to ensure AI agents can execute tasks with precision. Payloads are structured using Pydantic schemas, providing type safety and validation. This document describes the key components of payloads, intent modifiers, context references, and execution hints, and provides examples for common verbs.

Payload Components #

Payloads consist of three main types of parameters:

• Intent Modifiers: Parameters that alter the action’s execution, such as output format, style, or priority. These allow agents to customize behavior without changing the verb’s core intent.
• Context References: Identifiers linking to entities or states, such as document IDs or user IDs, ensuring the action targets the correct resource.
• Execution Hints: Metadata guiding how the response should be formatted or interpreted, such as language or output type.

Pydantic schemas enforce required fields, minimizing ambiguity and ensuring agents provide all necessary inputs.

Example Payloads #

Below are Pydantic schemas and example payloads for two common verbs, demonstrating these components.

SummarizeQuery (SUMMARIZE Verb) #

The SUMMARIZE verb processes a document to generate a summary, with modifiers for format and style.

from pydantic import BaseModel

class SummarizeQuery(BaseModel):
    document_id: str  # Context Reference: Identifies the document
    format: str = "text"  # Intent Modifier: text or bullets
    max_words: int = 50  # Intent Modifier: Maximum summary length
    style: str = "neutral"  # Intent Modifier: neutral, formal, casual
    output_format: str = "json"  # Execution Hint: json, text

Example Request:

{
  "document_id": "doc_001",
  "format": "text",
  "max_words": 20,
  "style": "neutral",
  "output_format": "json"
}

• Context Reference: document_id specifies the target document.
• Intent Modifiers: format, max_words, style customize the summary.
• Execution Hint: output_format ensures a JSON response.

NotifyQuery (NOTIFY Verb) #

The NOTIFY verb sends a message to a recipient, with modifiers for channel and priority.

from pydantic import BaseModel

class NotifyQuery(BaseModel):
    recipient: str  # Context Reference: Email or phone number
    message: str  # Intent Modifier: Message content
    channel: str = "email"  # Intent Modifier: email, sms
    priority: str = "normal"  # Intent Modifier: normal, high
    output_format: str = "json"  # Execution Hint: json, text

Example Request:

{
  "recipient": "user@example.com",
  "message": "Task completed",
  "channel": "email",
  "priority": "normal",
  "output_format": "json"
}

• Context Reference: recipient identifies the message target.
• Intent Modifiers: message, channel, priority define the notification.
• Execution Hint: output_format specifies JSON output.

Best Practices #

• Minimize Optional Fields: Use defaults (e.g., format="text") to reduce agent misinterpretation.
• Validate Inputs: Pydantic ensures type safety, preventing invalid requests.
• Document Impact: Use OpenAPI extensions (x-intent-impact) to clarify parameter effects (e.g., format=bullets changes response structure).

Next Steps #

• Learn about Responses to understand output formats.
• Explore ACTION Verbs for verb categories.
• Try Implementing Custom Verbs to define your own schemas.