API Design Best Practices for Generative Agent

As AI agents become the primary interface for many business operations, traditional API design patterns are failing. Poorly designed APIs can reduce AI agent accuracy and create frustrating user experiences. The solution? APIs designed specifically for AI consumption. Most AI agents use middleware to expose functions to the LLM and call underlying HTTP APIs, such as MCP or custom solutions. To streamline this process with Generative Agent, we built API Connections to enable your Generative Agent to work with any API, regardless of how it’s designed. Many customers still desire to revamp or redesign their APIs to make them more LLM and Generative Agent friendly. We’ve found several best practices that help you design APIs that are easily interpreted by Generative Agent and other AI agents.

API for Humans vs AI Agents

Most APIs are designed for human consumption, which relies on implicit dependencies like documentation, trial and error, training, and technical support. Real-time AI agents (like Generative Agent) must perform API calls in one shot. They rely exclusively on specifications to determine how to call the API. We recommend using OpenAPI specifications for this purpose.

To design APIs that are easily interpreted by Generative Agent or any other AI agent, you must prioritize machine-readability and explicit semantic context over human-centric documentation. AI agents can’t infer intent from documentation prose. They need structured, self-describing contracts that eliminate ambiguity.

Treat the API’s specification not as documentation about the API, but as an integral, machine-readable part of the API itself.

HTTP API and LLM Tools

In virtually all AI Agent use cases, middleware (such as MCP) handles transforming LLM requests to API calls. This need is critical as LLMs work best with targeted, RPC-like tool calls (such as update_address or refund_order with parameters for the ID or fields to update). They are not as successful with constructing actual HTTP API requests (such as a call_api function with parameters for verb, path, body, etc.). When you decide to update your APIs for AI agents, there are two approaches to consider:

Expose an API that is entirely focused on AI agents and let human developers work around it
- Your APIs will be focused on RPC-like tool calls
Expose an API that is designed for both human developers and AI agents
- Ideally this is a RESTful API where the middleware can convert RESTful actions into RPC-like tool calls

Most customers choose the second approach to maximize API usage by both human developers and AI agents. Our guidance below focuses on this approach, though it’s applicable if you opt for RPC-like API calls.

HTTP API Design

Guidance and best practices for designing HTTP APIs that will be used by AI agents.

Tool Call Design

Guidance and best practices for designing tool calls that will be used by AI agents.

API Design Principles

Being consistent and using common schema patterns makes it easier for AI agents. We show examples using OpenAPI specifications.

There are many good general API design guides out there such as Google’s API design guide.

Here are the design principles that will help your APIs be AI-ready:

Simplify Field Names

Use clear, descriptive, and simple field names. Avoid abbreviations that aren’t immediately clear.

Show Good vs. Bad Field Naming Examples

Good - Clear and descriptive

{
  "type": "object",
  "properties": {
    "customer_name": {
      "type": "string"
    },
    "order_date": {
      "type": "string"
    }
  }
}

Avoid - Cryptic or complex

{
  "type": "object", 
  "properties": {
    "cust_nm_001": {
      "type": "string"
    },
    "ord_dt_timestamp": {
      "type": "string"
    }
  }
}

Use Intuitive, Human-Friendly Concepts

Design APIs that work for both humans and AI agents by balancing technical primitives with human-friendly concepts. Esoteric terms like “record”, “details”, or “session” are difficult for humans to understand without context—AI agents will struggle even more. Instead, design around resources that can express their current state and requirements clearly. This makes it easier for AI agents to understand what data is needed and how to provide it. This will make your APIs easier to expand and map to RPC-like tool calls that work well with Generative Agent.

Be Verbose in Descriptions

Use the summary and description fields in OpenAPI for each endpoint and parameter. Describe the purpose in clear, simple language. Generative Agent can use this text to map a user’s natural language request (e.g., “find a customer by their email”) to the correct API call.

Show Example of Descriptive Schema

{
  "properties": {
    "order_status": {
      "type": "string",
      "description": "Current status of the order (pending, shipped, delivered)",
      "enum": ["pending", "shipped", "delivered"]
    }
  }
}

Define Strict Schemas

Meticulously define the data structures for every request and response using JSON Schema within the OpenAPI document. Specify data types (string, integer), formats (date-time, email), and constraints (minLength, maximum). This is how an agent knows exactly what to send and how to parse the result.

Standardize Data Formats

Use universal standards for common data types:

Timestamps: ISO 8601 format (2024-01-15T10:30:00Z)
Currency: ISO 4217 codes (USD, EUR)
Phone numbers: E.164 format (+1234567890)

Consistent Naming Conventions

Use a predictable naming schema for your API endpoints such as plural nouns for collections (/users, /orders). Maintain consistent case style (e.g., camelCase for JSON properties).

Provide Rich Context

Don’t just return an ID. If you have a userId, also include a userName or userEmail. Design API responses to be self-contained and descriptive.

Show Rich Context Example

{
  "status": {
    "code": "A",
    "label": "Active"
  }
}

Ensure Idempotency

For operations like PUT and DELETE, ensure they can be called multiple times with the same input and produce the same result. Generative Agent may need to retry operations, and idempotency makes this safe.

Design Structured Errors

Provide detailed error information that AI systems can understand. Provide a structured JSON error payload that an agent can parse.

Show Structured Error Example

{
  "error": {
    "code": "InvalidParameter",
    "message": "The 'email' parameter is not a valid email address.",
    "target": "email",
    "details": "https://developer.example.com/errors#InvalidParameter"
  }
}

Cursor Pagination

Implement cursor-based pagination for list endpoints. Include metadata for navigating to next/previous pages. Provide total count when possible.

Essential OpenAPI Elements

We recommend using OpenAPI specifications for your APIs. Here are some essential elements to consider:

Descriptive Documentation

Use clear summary and description fields for each endpoint
Describe parameters and responses in simple language
Include examples that show expected usage

Unique Operation IDs

Provide descriptive operationId values (e.g., getUserById, createOrder)
Use consistent naming conventions across your API
Avoid generic names like getData or processRequest

Tool Call Design Best Practices

Granular Tool Names for Specific Use Cases

Generative Agent and other LLMs work best with targeted, RPC-like tool calls. If you want to have Generative Agent update a user’s address, instead of directly calling a generic update_user tool, you can create a tool called update_user_address.

Start Simple, Expand as NeededYou can start with basic CRUD tools based on your existing APIs, but expand on them to be more specific to the task. A basic exposing of RESTful API results in tools like create_user, update_user which may be okay for some use cases, but often you’ll end up exposing specific tools for a specific task.

Flatten Complex Structures

Often a good RESTful design has logical nesting for different entities within a given resource. But LLMs can have a hard time understanding deeply nested objects. Flatten nested objects into a single level. Avoid deep nesting of objects.

Show Flat vs. Nested Structure Examples

Good - Flat structure

{
  "type": "object",
  "properties": {
    "shipping_street": {
      "type": "string"
    },
    "shipping_city": {
      "type": "string"
    },
    "shipping_country": {
      "type": "string"
    }
  }
}

Avoid - Deep nesting

{
  "type": "object",
  "properties": {
    "shipping": {
      "type": "object",
      "properties": {
        "address": {
          "type": "object",
          "properties": {
            "street": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "country": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Focus on Essential Data

Remove optional or additional fields that are not directly needed for the specific task
Only expose the specific fields from the API that are needed for the specific task
The more fields, the more likely Generative Agent may make a mistake in providing unnecessary information or getting confused by a large API response

Schema Consistency Across Tools

When exposing multiple tools to Generative Agent, ensure you expose consistent naming to Generative Agent regardless of the underlying system. If you have a person called a user in one API and an account in another, it may confuse Generative Agent. You should use a consistent naming convention across all the APIs and ensure you use that same naming in the task instructions.

Cross Field Relationships

AI agents need explicit guidance about how fields relate to each other. Document field dependencies, constraints, and interactions clearly in your schema descriptions. Use descriptive field names that indicate relationships and explicitly document when one field’s value affects another field.

Show Example: Field Dependencies

{
  "type": "object",
  "properties": {
    "payment_method": {
      "type": "string",
      "description": "Payment method type. When set to 'credit_card', the 'card_details' field becomes required.",
      "enum": ["credit_card", "bank_transfer", "paypal"]
    },
    "card_details": {
      "type": "object",
      "description": "Required when payment_method is 'credit_card'. Ignored for other payment methods.",
      "properties": {
        "card_number": {"type": "string"},
        "expiry_date": {"type": "string"}
      }
    }
  }
}

Getting Started

Build

Tasks & Functions

Test

Observe

Integrate

Reporting & Security

API Design Best Practices for Generative Agent

API for Humans vs AI Agents

HTTP API and LLM Tools

HTTP API Design

Tool Call Design

API Design Principles

Simplify Field Names

Use Intuitive, Human-Friendly Concepts

Be Verbose in Descriptions

Define Strict Schemas

Standardize Data Formats

Consistent Naming Conventions

Provide Rich Context

Ensure Idempotency

Design Structured Errors

Essential OpenAPI Elements

Descriptive Documentation

Unique Operation IDs

Tool Call Design Best Practices

Granular Tool Names for Specific Use Cases

Flatten Complex Structures

Focus on Essential Data

Schema Consistency Across Tools

Cross Field Relationships

Getting Started

Build

Tasks & Functions

Test

Observe

Integrate

Reporting & Security

​API for Humans vs AI Agents

​HTTP API and LLM Tools

HTTP API Design

Tool Call Design

​API Design Principles

​Simplify Field Names

​Use Intuitive, Human-Friendly Concepts

​Be Verbose in Descriptions

​Define Strict Schemas

​Standardize Data Formats

​Consistent Naming Conventions

​Provide Rich Context

​Ensure Idempotency

​Design Structured Errors

​Cursor Pagination

​Essential OpenAPI Elements

​Descriptive Documentation

​Unique Operation IDs

​Tool Call Design Best Practices

​Granular Tool Names for Specific Use Cases

​Flatten Complex Structures

​Focus on Essential Data

​Schema Consistency Across Tools

​Cross Field Relationships

API for Humans vs AI Agents

HTTP API and LLM Tools

API Design Principles

Simplify Field Names

Use Intuitive, Human-Friendly Concepts

Be Verbose in Descriptions

Define Strict Schemas

Standardize Data Formats

Consistent Naming Conventions

Provide Rich Context

Ensure Idempotency

Design Structured Errors

Cursor Pagination

Essential OpenAPI Elements

Descriptive Documentation

Unique Operation IDs

Tool Call Design Best Practices

Granular Tool Names for Specific Use Cases

Flatten Complex Structures

Focus on Essential Data

Schema Consistency Across Tools

Cross Field Relationships