AgenticAPI supports contextual and dynamic intent through verbs that adapt to the specific context or target of a task, enabling flexible, intent-driven interactions for AI agents. These verbs, often simple and versatile (e.g., CHECK, GET, SET), derive their meaning from the parameters and context provided, allowing a single verb to serve multiple purposes. This document explains contextual/dynamic intent, focusing on the CHECK verb as an example, and generalizes to other similar verbs.

Understanding Contextual / Dynamic Intent #

Traditional APIs use rigid endpoints for specific tasks (e.g., GET /weather). In contrast, AgenticAPI’s contextual verbs rely on parameters to define the action’s target or scope, making them highly adaptable. For example, CHECK can mean “check the weather,” “check email,” or “check balance,” depending on the target parameter. This flexibility reduces the need for numerous endpoints, streamlining API design and enhancing agent usability.

Contextual verbs typically belong to the Acquire, Compute, Transact, or Communicate categories, with their behavior determined by:

• Target Parameter: Specifies the object or resource (e.g., weather, email).
• Context References: Provide additional context (e.g., user_id, location).
• Intent Modifiers: Customize execution (e.g., format, priority).

Examples of contextual verbs include CHECK, GET, SET, TAKE, RUN, OPEN, START, FIND, SHOW, CALL, PULL, MAKE, SEND, TURN, and BREAK, each supporting varied tasks based on parameters.

Example: CHECK Verb #

The CHECK verb, categorized as Acquire or Compute, retrieves or verifies the status of a resource or condition. Its behavior depends on the target parameter.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class CheckQuery(BaseModel):
    target: str  # e.g., weather, email, balance
    context: Dict[str, Any] = {}  # e.g., location, user_id
    output_format: str = "json"  # json, text

@app.api_route("/check", methods=["CHECK"])
async def check_resource(query: CheckQuery):
    # Simulate checking based on target
    if query.target == "weather":
        result = {"condition": "sunny", "temperature": "25C"}
    elif query.target == "email":
        result = {"new_messages": 3}
    elif query.target == "balance":
        result = {"amount": 1000, "currency": "USD"}
    else:
        raise ValueError(f"Unsupported target: {query.target}")
    return {"status": "completed", "result": result}

Request (Check Weather):

curl -X CHECK http://localhost:8000/check -H "Content-Type: application/json" -d '{
  "target": "weather",
  "context": {"location": "New York"},
  "output_format": "json"
}'

Response:

{
  "status": "completed",
  "result": {
    "condition": "sunny",
    "temperature": "25C"
  }
}

Request (Check Email):

curl -X CHECK http://localhost:8000/check -H "Content-Type: application/json" -d '{
  "target": "email",
  "context": {"user_id": "user1"},
  "output_format": "json"
}'

Response:

{
  "status": "completed",
  "result": {
    "new_messages": 3
  }
}

Other Contextual Verbs #

The dynamic intent principle applies to many verbs, each adapting to the target or context:

• SET: Configure settings (e.g., SET alarm, SET temperature).
• TAKE: Perform actions (e.g., TAKE picture, TAKE notes).
• RUN: Execute processes (e.g., RUN report, RUN diagnostics).
• OPEN: Access or initiate (e.g., OPEN app, OPEN discussion).
• START: Begin tasks (e.g., START timer, START project).
• FIND: Locate items (e.g., FIND file, FIND restaurant).
• SHOW: Display information (e.g., SHOW results, SHOW location).
• CALL: Initiate communication (e.g., CALL someone, CALL meeting).
• PULL: Extract data (e.g., PULL data, PULL file).
• MAKE: Create or decide (e.g., MAKE call, MAKE decision).
• SEND: Transmit information (e.g., SEND email, SEND feedback).
• TURN: Adjust states (e.g., TURN on lights, TURN in assignment).
• BREAK: Interrupt or analyze (e.g., BREAK ice, BREAK down data).

These verbs share a common structure, using target and context to define their specific intent, making them versatile for agent-driven tasks.

Benefits #

• Flexibility: Single verbs support multiple tasks, reducing endpoint proliferation.
• Agent Reasoning: Dynamic intent allows agents to adapt actions based on context.
• Simplified Design: Fewer endpoints simplify API maintenance and scalability.

Best Practices #

• Clear Target Definitions: Document valid target values in OpenAPI schemas.
• Validate Context: Use Pydantic to enforce required context fields.
• Annotate Intent: Add x-intent-impact to clarify target effects.

Next Steps #

• Learn about Chaining to combine contextual verbs.
• Explore Payloads and Parameters for input details.
• Try Implementing Custom Verbs to create dynamic verbs.