AgenticAPI redefines API design by replacing traditional CRUD operations (Create, Read, Update, Delete) with action-oriented verbs that reflect specific tasks or intentions. These verbs, part of the ACTION framework, enable AI agents to interact with APIs in a way that aligns with real-world objectives, such as fetching data, summarizing content, or sending notifications. This document explains the verb categories and provides examples to illustrate their usage.
Verb Categories #
ACTION verbs are organized into five categories, each representing a distinct type of operation:
- Acquire: Retrieve data or resources (e.g., fetching a document or user profile).
- Compute: Process or analyze information (e.g., summarizing text, validating input).
- Transact: Perform state-changing actions (e.g., registering a user, booking a meeting).
- Communicate: Send messages or notifications (e.g., alerting a team, emailing a user).
- Orchestrate: Coordinate multiple actions in workflows (e.g., chaining tasks).
Each verb is implemented as a custom HTTP method, allowing agents to execute tasks with clear intent, documented using OpenAPI extensions for discoverability.
Example Verbs #
Below are examples of common verbs, demonstrating their purpose and implementation.
FETCH (Acquire) #
The FETCH
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class FetchQuery(BaseModel):
document_id: str
output_format: str = "json"
@app.api_route("/document", methods=["FETCH"])
async def fetch_document(query: FetchQuery):
# Simulate fetching a document
return {
"content": "This is the document content.",
"title": "Sample Document"
}Request:
curl -X FETCH http://localhost:8000/fetch -H "Content-Type: application/json" -d '{
"document_id": "doc_001",
"output_format": "json"
}'Response:
{
"content": "This is the document content.",
"title": "Sample Document"
}SUMMARIZE (Compute) #
The SUMMARIZE verb processes a document to generate a concise summary, configurable by format and style.
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class SummarizeQuery(BaseModel):
document_id: str
format: str = "text"
max_words: int = 50
style: str = "neutral"
@app.api_route("/document", methods=["SUMMARIZE"])
async def summarize_document(query: SummarizeQuery):
# Simulate summarization
return {
"summary": "Report highlights revenue growth and cost reduction.",
"title": "Annual Report"
}Request:
curl -X SUMMARIZE http://localhost:8000/document -H "Content-Type: application/json" -d '{
"document_id": "doc_001",
"format": "text",
"max_words": 20,
"style": "neutral"
}'
Response:
{
"summary": "Report highlights revenue growth and cost reduction.",
"title": "Annual Report"
}
NOTIFY (Communicate) #
The NOTIFY verb sends a message to a recipient via a specified channel (e.g., email, SMS).
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class NotifyQuery(BaseModel):
recipient: str
message: str
channel: str = "email"
priority: str = "normal"
@app.api_route("/users", methods=["NOTIFY"])
async def notify_user(query: NotifyQuery):
# Simulate notification
return {
"status": f"Notification sent via {query.channel}",
"recipient": query.recipient,
"message": query.message
}
Request:
curl -X NOTIFY http://localhost:8000/notify -H "Content-Type: application/json" -d '{
"recipient": "user@example.com",
"message": "Task completed",
"channel": "email",
"priority": "normal"
}'
Response:
{
"status": "Notification sent via email",
"recipient": "user@example.com",
"message": "Task completed"
}
Benefits #
- Clear Intent: Verbs like
SUMMARIZEorNOTIFYexplicitly convey task purpose, unlike genericPOSTorGET. - Agent-Friendly: AI agents can reason about actions based on verb categories.
- Modularity: Each verb is self-contained, simplifying API design and maintenance.
Next Steps #
- Explore Payloads and Parameters to define verb inputs.
- Learn about Responses for output structures.
- Try Implementing Custom Verbs to create your own verbs.
