The new way to API.

AI Agent Integration

Table Of Contents

AgenticAPI is designed to empower AI agents to execute tasks autonomously by providing action-oriented verbs and orchestration capabilities. While full agent integration is planned for AgenticAPI v0.4.0, this document outlines how agents can connect to AgenticAPI, focusing on invoking chained workflows via the /chain endpoint. It provides a forward-looking example of an agent interacting with AgenticAPI, demonstrating how to trigger complex tasks programmatically.

How Agents Interact with AgenticAPI #

AI agents interact with AgenticAPI by sending HTTP requests to action verb endpoints (e.g., SUMMARIZE /document, NOTIFY /user) or the /chain endpoint for workflows. Key integration points include:

  • Action Verbs: Agents invoke verbs like FETCH, SUMMARIZE, or NOTIFY to perform specific tasks.
  • Chaining: The /chain endpoint allows agents to coordinate multiple verbs in a sequence.
  • Semantic Discoverability: OpenAPI extensions (x-action, x-category) enable agents to explore capabilities (planned DISCOVER /actions endpoint in v0.4.0).
  • Error Handling: Agents process response status and errors to adapt workflows.

Agents typically use HTTP clients (e.g., Python’s httpx) to send requests, parsing JSON responses to guide decision-making.

Example: Agent Calling /chain #

The following Python script demonstrates an AI agent invoking a chained workflow to fetch a document, summarize it, and notify a user. This example is illustrative, as full agent integration is planned for v0.4.0.

Python
import httpx
import json
import logging

# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def run_agent_workflow():
    url = "http://localhost:8000/chain"
    headers = {"Content-Type": "application/json"}
    payload = {
        "chain": [
            {
                "verb": "FETCH",
                "path": "/fetch",
                "params": {
                    "document_id": "doc_001",
                    "output_format": "json"
                }
            },
            {
                "verb": "SUMMARIZE",
                "path": "/document",
                "params": {
                    "document_id": "doc_001",
                    "format": "text",
                    "max_words": 20,
                    "style": "neutral",
                    "output_format": "json"
                }
            },
            {
                "verb": "NOTIFY",
                "path": "/notify",
                "params": {
                    "recipient": "user@example.com",
                    "message": "Summary completed",
                    "channel": "email",
                    "priority": "normal",
                    "output_format": "json"
                }
            }
        ]
    }

    try:
        with httpx.Client() as client:
            response = client.post(url, headers=headers, json=payload)
            response.raise_for_status()
            results = response.json()["results"]
            logger.info("Workflow completed successfully")
            return results
    except httpx.HTTPStatusError as e:
        logger.error(f"Workflow failed: {e.response.status_code} - {e.response.text}")
        return None

# Run the agent
results = run_agent_workflow()
if results:
    print(json.dumps(results, indent=2))

Expected Response:

JSON
[
  {
    "step": {
      "verb": "FETCH",
      "path": "/fetch",
      "params": {"document_id": "doc_001", "output_format": "json"}
    },
    "result": {
      "content": "Document text...",
      "title": "Report"
    }
  },
  {
    "step": {
      "verb": "SUMMARIZE",
      "path": "/document",
      "params": {
        "document_id": "doc_001",
        "format": "text",
        "max_words": 20,
        "style": "neutral",
        "output_format": "json"
      }
    },
    "result": {
      "summary": "Report highlights key trends.",
      "title": "Report"
    }
  },
  {
    "step": {
      "verb": "NOTIFY",
      "path": "/notify",
      "params": {
        "recipient": "user@example.com",
        "message": "Summary completed",
        "channel": "email",
        "priority": "normal",
        "output_format": "json"
      }
    },
    "result": {
      "status": "Sent",
      "recipient": "user@example.com"
    }
  }
]
  • Agent Logic: Sends a /chain request to execute FETCH, SUMMARIZE, and NOTIFY.
  • Error Handling: Logs failures and handles HTTP errors.
  • Planned for v0.4.0: Full agent integration with dynamic discovery and intent weighting.

Best Practices #

  • Use Chaining: Leverage /chain for multi-step tasks to reduce agent complexity.
  • Parse Responses: Check status and error fields to adapt workflows.
  • Plan for Discoverability: Prepare agents to use DISCOVER /actions (v0.4.0) for dynamic endpoint exploration.
  • Secure Requests: Implement authentication (e.g., API keys) when available in v0.4.0.

Next Steps #

What are your feelings
Updated on May 29, 2025