In Part 1, we explored the paradigm shift of building for AI agents. In Part 2, we dug into how LLMs work. Now let's tackle the practical question: how do you design APIs that agents can use reliably?

The answer requires rethinking some fundamental assumptions about software architecture.

The Traditional API Model

Historically, APIs have been designed around discrete operations:

POST /requests - Create a request
GET /requests - Get all requests
PUT /requests/:id - Edit a request
DELETE /requests/:id - Delete a request

These CRUD operations (Create, Read, Update, Delete) map cleanly to database operations. They're granular, composable, and give developers maximum flexibility. A frontend can call these endpoints in any combination to build complex workflows.

This design philosophy has served us well for decades. But it creates problems for AI agents.

Why Granular Fails for Agents

Remember from Part 2: agents need to solve the same maze every single time. When you give an agent granular tools, it has to figure out the correct sequence for every request.

Consider what happens when a legal question comes in. With granular APIs, the agent needs to:

Recognize that this is a question requiring research
Call the question condenser API
Call the document retrieval API
Call the passage extraction API
Call the answer generation API with the right context

Each step is a decision point. Each decision point is a chance for error. If the agent skips step 2, the retrieval might be less accurate. If it forgets step 3, it might hallucinate an answer from training data instead of your documents.

The chance of errors keeps increasing if you build this way. Instead, agent tools should directly match human intentions.

Intention-Based API Design

The shift is from "what operations are possible" to "what is the user trying to accomplish."

Instead of exposing:

condense_question()
fetch_documents()
extract_passages()
generate_answer()

You expose:

answer_question_from_documents()

The agent calls one tool that encapsulates the entire workflow we've already validated. The maze gets solved once, by us as system designers, not every single time by the agent.

Other examples of intention-based tools:

| Granular (Old) | Intention-Based (New) | |----------------|----------------------| | create_request(), add_comment() | submit_intake_with_first_pass() | | search_contracts(), extract_terms(), compare() | research_contract_question() | | fetch_template(), fill_fields(), validate() | draft_document_from_template() |

The Reliability Math

Here's why this matters quantitatively.

If each agent decision is 95% reliable (which is quite good), then:

1 decision: 95% success
3 decisions: 86% success
5 decisions: 77% success
10 decisions: 60% success

By consolidating five granular operations into one intention-based tool, you're not just simplifying the agent's job. You're dramatically improving reliability.

The goal is to make the agent's success rate match the reliability of traditional software. Users don't accept microwaves that fail 5% of the time. They shouldn't have to accept that from AI agents either.

Flipping Conventional Wisdom

This creates an interesting tension with how we've traditionally thought about system design.

Old thinking: The more deterministic your path, the more reliable your system. Define every step precisely.

New thinking: For agents, giving more flexibility (within bounded tools) can increase reliability, because you're letting the agent match its behavior to the actual intention rather than forcing it through a rigid sequence.

The key insight: human intentions vary. What someone means by "handle this request" is slightly different each time based on context. A rigid sequence of CRUD operations can't adapt to that variance. But a well-designed intention-based tool can encapsulate the logic needed to handle those variations.

Practical Implementation

So how do you build intention-based APIs? A few principles:

Start with User Intentions

Before designing any tool, ask: "What is the human trying to accomplish?" Don't start with your data model or existing operations. Start with the job to be done.

Encapsulate Validated Workflows

Each tool should contain a workflow you've already validated works reliably. The agent shouldn't be inventing new processes. It should be triggering proven ones.

Handle Edge Cases Inside the Tool

If there are branches in your workflow (e.g., "if it's a policy question, do X; if it's a contract question, do Y"), handle that logic inside the tool. Don't make the agent figure out which tool to call.

Provide Rich Context in Responses

When a tool completes, give the agent everything it needs to continue. Include not just the result, but metadata about what was done, what confidence level applies, and what the next logical step might be.

Design for Composability at the Intention Level

You can still compose tools, just at a higher level. An agent might call research_question(), then draft_response(), then request_human_review(). That's three decisions, not fifteen.

The Path Forward

We're still in the early stages of understanding how to build reliable agent systems. The patterns are emerging, but they're not yet as mature as the CRUD conventions that have guided API design for decades.

What's clear is that the old assumptions don't fully apply. Building for AI agents requires rethinking interfaces from the ground up, not just adding an AI layer on top of existing architecture.

The platforms that get this right will define the next generation of enterprise software. The ones that don't will find themselves fighting an uphill battle against technical debt and reliability problems.

When you don't have that debt to clear, building AI-native becomes much easier.

The paradigm shift is here. The question is whether you're building for it from the start or trying to retrofit it later.

This concludes our 3-part series on Building for AI. For more on how Coheso approaches AI-native design for legal teams, request a demo.

Building for AI, Part 3: Intention-Based API Design