OpenAPI as the Contract Between AI Agents and Enterprise Systems

Deep Dive into Swagger, REST APIs, Tools and Microsoft Copilot Studio

Introduction

Swagger and OpenAPI are traditionally studied as API technologies.

A developer creates a REST API.

Another developer needs to consume it.

An OpenAPI document describes the available endpoints, parameters, authentication mechanisms and responses.

That traditional mental model remains correct.

However, the emergence of AI Agents introduces a much more interesting perspective.

The consumer of an API is no longer necessarily a developer writing deterministic code.

It can be an AI Agent.

Microsoft Copilot Studio can expose external systems to an Agent through mechanisms such as:

• Prebuilt connectors
• Custom connectors
• REST API Tools
• Agent flows
• Model Context Protocol (MCP)
• Other Agents

The architecture therefore changes from:

Human
↓
Application
↓
Code
↓
API

to something potentially much more dynamic:

Human
↓
Natural Language
↓
Agent
↓
Generative Orchestration
↓
Tool Selection
↓
API Contract
↓
REST API
↓
Enterprise System

This makes OpenAPI much more than API documentation.

In an Agent architecture, OpenAPI can participate in defining the boundary between probabilistic AI reasoning and deterministic software operations.

That distinction is fundamental for understanding enterprise Agents.

1. Two Very Different Worlds

An Agent integration connects two fundamentally different computational models.

On one side we have the Large Language Model.

Its world contains concepts such as:

Natural language

Intent

Context

Semantic similarity

Reasoning

Instructions

Knowledge

Retrieval

Grounding

Generative Orchestration

On the other side we have traditional software systems.

Their world contains:

HTTP

GET

POST

PATCH

DELETE

URLs

Headers

Parameters

JSON

Authentication

Status codes

Schemas

Types

The Agent needs a bridge between these worlds.

OpenAPI can participate in creating that bridge.

2. Natural Language Is Ambiguous

Consider a user asking:

“What will the weather be like in São Paulo tomorrow?”

This sentence makes perfect sense to a human.

But a REST API doesn’t understand that sentence automatically.

The Open-Meteo Forecast API expects structured information.

Conceptually:

GET /v1/forecast

with parameters such as:

latitude
longitude
daily
timezone
forecast_days

The Agent therefore faces a transformation problem:

Natural Language

↓

Structured Operation

This transformation is one of the central responsibilities of Agent orchestration.

3. From Intent to Function

Conceptually, the Agent needs to transform:

"What will the weather be like in São Paulo tomorrow?"

into something resembling:

Tool:
GetWeatherForecast
Inputs:
latitude = ...
longitude = ...
forecast date = tomorrow

This is extremely important.

The LLM doesn’t simply generate the HTTP request arbitrarily.

Ideally, it selects a defined capability whose interface constrains what can be executed.

That capability might ultimately be represented by an API operation.

4. OpenAPI Defines the Boundary

Suppose our Swagger definition contains:

operationId: GetWeatherForecast

and inputs:

latitude
longitude
timezone
forecast_days

The Agent doesn’t need to invent an API contract.

The contract already exists.

We can therefore think:

Natural language

↓

Probabilistic interpretation

↓

Defined Tool

↓

Structured parameters

↓

Deterministic API

This boundary is extremely valuable.

Before the boundary:

AI reasoning

After the boundary:

software contract

5. The Agent Should Not Invent APIs

Imagine an Agent deciding:

“Maybe Open-Meteo has /weather/tomorrow/sao-paulo.”

That would be unacceptable integration architecture.

The Agent shouldn’t invent:

Endpoints

HTTP methods

Parameter names

Authentication mechanisms

Response schemas

The API contract defines these elements.

OpenAPI tells the platform:

These are the operations that exist.

These are the parameters.

These are the types.

These are the responses.

These are the security requirements.

Therefore:

The Agent decides which capability to use.

The API contract defines how that capability can be called.

6. A Fundamental Agent Architecture

A useful model is:

User Intent

↓

Agent

↓

Instructions

↓

Generative Orchestration

↓

Tool Selection

↓

Tool Contract

↓

Structured Inputs

↓

API

↓

Structured Outputs

↓

Agent

↓

Natural Language Response

The LLM operates mainly around the structured operation.

It doesn’t replace the operation.

7. OpenAPI as a Tool Contract

Traditionally:

OpenAPI = API Contract

In an Agent architecture we can extend the mental model:

OpenAPI = API Contract + Tool Contract

Consider:

operationId: GetCurrentWeather
description:
  Retrieves current weather observations
  for a geographical location.
parameters:
  latitude
  longitude

This information describes a capability.

The Agent can conceptually understand:

Capability

Get current weather.

Required information

Latitude and longitude.

Result

Weather information.

That looks remarkably similar to a function signature.

8. APIs Begin to Look Like Functions

Traditional REST:

GET /v1/forecast

Agent-oriented interpretation:

GetWeatherForecast(
    latitude,
    longitude
)

This abstraction is powerful.

The Agent doesn’t need to think primarily in terms of:

HTTP

URLs

query strings

headers

Instead, orchestration can reason about:

Tools

9. Tool Calling

This leads directly to the concept of Tool Calling.

An LLM is extremely good at producing natural language.

But enterprise Agents must frequently interact with the real world.

For example:

Get weather

Create ticket

Search customer

Update SharePoint item

Retrieve invoice

Start approval

Check inventory

Send notification

These operations shouldn’t exist only as natural-language responses.

They must execute real software operations.

Therefore:

LLM

↓

Tool Call

↓

Deterministic System

↓

Result

↓

LLM

This is one of the foundations of modern Agent architecture.

10. Microsoft Copilot Studio Tools

In current Copilot Studio architecture, an Agent can be extended with several Tool mechanisms.

Depending on the Agent/harness and scenario, Microsoft currently documents capabilities including:

• Connectors
• Custom connectors
• REST APIs
• Agent flows / Workflows
• MCP
• Prompts
• Other Agent capabilities

The exact availability can depend on the Agent experience and harness.

This is why we should avoid thinking:

Tool = Power Automate Flow

A Flow can be a Tool.

But Tool is the broader abstraction:

Something the Agent can invoke to obtain information or perform an operation.

11. REST API as a Copilot Studio Tool

Copilot Studio currently supports adding REST APIs as Tools in the Standard harness experience.

Microsoft describes three particularly important pieces:

1. OpenAPI specification
2. Authentication configuration
3. Descriptions that help the language model determine when to invoke the API

This is architecturally fascinating.

The OpenAPI file isn’t only telling Power Platform how to create an HTTP request.

Parts of its semantic definition participate in explaining the capability available to the Agent.

12. The New Importance of description

In traditional API development, developers sometimes treat descriptions as secondary documentation.

For example:

description: Gets data.

Technically, that might be enough for a human who already knows the API.

For an Agent, it is poor design.

Compare:

description: Gets data.

with:

description:
  Retrieves current and forecast weather
  information for a geographical location
  using latitude and longitude.

The second description provides semantic meaning.

Microsoft explicitly recommends clear Tool names and descriptions because orchestration uses them when determining when a Tool should be invoked.

Therefore:

Description becomes part of Agent architecture.

13. Description Is Almost a Prompt

This leads to an interesting idea.

Traditional API description:

Documentation for developer.

Agent-era API description:

Documentation for developer

semantic information for orchestration.

The line between:

API metadata

and

AI instructions

becomes thinner.

Not identical — but related.

A Tool description can influence whether the orchestration layer considers that Tool relevant to a request.

14. Poor Tool Design

Imagine an Agent with these Tools:

Tool1
Tool2
Tool3

Descriptions:

Runs operation.
Gets information.
Processes data.

The Agent has very little semantic information.

Now imagine:

GetCurrentWeather
GetWeatherForecast
GetHistoricalWeather

with precise descriptions.

The capability space becomes much clearer.

Therefore good Agent integration architecture requires:

semantic API design

not merely syntactically correct API design.

15. Tool Selection

Suppose our Agent exposes:

GetCurrentWeather

GetWeatherForecast

GetHistoricalWeather

The user says:

“What is the temperature right now in Cape Town?”

The orchestrator can identify:

Current weather request

↓

GetCurrentWeather

Another user asks:

“Will it rain this weekend?”

Now:

Future weather request

↓

GetWeatherForecast

Another asks:

“What was the temperature last Christmas?”

Potentially:

Historical request

↓

GetHistoricalWeather

This demonstrates why Tool descriptions matter.

16. The Agent Is Performing Semantic Routing

Traditional application:

if requestType == "current"
    call CurrentWeather()
if requestType == "forecast"
    call Forecast()

The developer writes routing logic.

With Generative Orchestration, part of this routing can become semantic.

Conceptually:

User Intent

↓

LLM Planner

↓

Available Capabilities

↓

Semantic Match

↓

Tool

This is a major architectural change.

17. Generative Orchestration

Microsoft describes Generative Orchestration as an LLM-driven planning layer.

Its responsibilities can include:

Interpreting user intent

Breaking requests into steps

Selecting appropriate Tools

Selecting Knowledge

Selecting Topics

Selecting other Agents

Managing data between steps

This means our architecture is no longer simply:

User

↓

Topic

↓

Action

Instead, it can become:

User

↓

Planner

↓

Plan

↓

Capability A

↓

Capability B

↓

Knowledge

↓

Capability C

↓

Final response

18. Open-Meteo Example

Consider:

“I’m hiking Table Mountain tomorrow morning. What weather should I expect?”

Potential architecture:

User

↓

Agent

↓

Interpret request

↓

Identify location

↓

Determine coordinates

↓

Call Weather Forecast Tool

↓

Open-Meteo

↓

Receive forecast

↓

Agent

↓

Explain weather in conversational form

The API doesn’t know what hiking is.

Open-Meteo only knows weather data.

The Agent provides contextual interpretation.

This separation is healthy.

19. API Responsibility vs Agent Responsibility

Open-Meteo should answer:

Temperature

Wind

Rain

Weather conditions

Forecast data

The Agent can answer:

“What does this mean for the user’s question?”

This gives us:

API

= factual operational data

Agent

= contextual interpretation

That distinction is extremely important.

20. Don’t Ask the LLM to Do the API’s Job

Suppose the user asks:

“What’s the current temperature?”

If a real-time Weather Tool exists, we should not rely on the model’s training data to invent a current temperature.

The correct architecture is:

Current information required

↓

Call Tool

↓

Obtain current data

↓

Generate answer

This is conceptually similar to our earlier Knowledge experiments.

A model may know general facts.

But current operational information should come from an appropriate current data source.

21. Knowledge vs Tool

This becomes a crucial distinction.

Knowledge

Answers:

What information can I retrieve and use as evidence/context?

Examples:

Corporate policy

Technical manual

Employee handbook

Product documentation

Tool

Answers:

What operation can I execute?

Examples:

Get weather

Create SharePoint item

Retrieve current order status

Send email

Start approval

Call external API

Therefore:

Knowledge = information

Tool = capability

22. Read Tools Blur the Boundary Slightly

There is an interesting nuance.

Consider:

GetWeatherForecast

It technically doesn’t modify anything.

It retrieves information.

So why isn’t it Knowledge?

Because it is still an executable API operation returning dynamic structured data.

This gives us a useful distinction:

Knowledge

↓

Retrieval over information sources

versus:

Tool

↓

Execution of a defined capability

Even when that capability is read-only.

23. Static vs Dynamic Information

Consider:

“What is the company’s severe-weather policy?”

Best candidate:

SharePoint Knowledge

Now:

“Is it raining in Cape Town?”

Best candidate:

Weather Tool

And:

“Given tomorrow’s weather and our severe-weather policy, should the employee follow the remote-work procedure?”

Now we potentially combine:

Weather Tool

SharePoint Knowledge

Agent reasoning

This is where Agent architecture becomes powerful.

24. Combining Knowledge and Tools

Architecture:

User Request

↓

Agent

↓

Generative Orchestration

↓

Weather Tool

↓

Open-Meteo

↓

Current/Forecast Data

SharePoint Knowledge

↓

Corporate Policy

↓

Grounding

↓

Agent

↓

Contextual Response

This is much richer than either component independently.

25. Tools Can Feed Other Tools

Now imagine the user says:

“What’s the weather in Cape Town?”

Our Weather Tool requires:

latitude

longitude

But the user supplied:

Cape Town

Another Tool might expose:

GetCoordinates(city)

Then:

User

↓

Agent

↓

GetCoordinates(“Cape Town”)

↓

latitude

longitude

↓

GetWeatherForecast(latitude, longitude)

↓

Weather

This is Tool chaining.

26. Tool Chaining

Tool chaining means the output of one capability becomes input to another.

Conceptually:

Tool A

↓

Output A

↓

Input B

↓

Tool B

↓

Output B

The Generative Orchestration guidance from Microsoft explicitly discusses composing and chaining actions, topics and knowledge as part of larger plans.

This moves us beyond simple chatbot design.

27. The Agent as an Integration Orchestrator

Traditional integration architecture often contains:

Application

↓

Integration layer

↓

APIs

An Agent introduces another possible layer:

Human

↓

Natural Language

↓

Agent

↓

Semantic Orchestration

↓

Integration Capabilities

↓

Enterprise Systems

The Agent doesn’t replace the integration layer.

It introduces a natural-language and reasoning layer above it.

28. Determinism Still Matters

This is a crucial principle.

An LLM is probabilistic.

An API contract should be deterministic.

For example:

Agent may decide:

“GetWeatherForecast is relevant.”

But once selected:

latitude must be number

longitude must be number

endpoint is fixed

HTTP method is fixed

response schema is defined

This creates an important architecture:

Probabilistic decision

↓

Deterministic execution

That is one of the most useful ways to think about enterprise Agents.

29. Schema as a Guardrail

Suppose latitude is defined:

type: number

The Agent shouldn’t send:

latitude = "I think somewhere in Brazil"

The contract requires structured input.

Schemas therefore provide a form of constraint.

They don’t solve every AI safety problem.

But they reduce the space of possible interactions between the LLM and external systems.

30. Inputs Are Agent Interfaces

Traditional API engineering asks:

“What parameters does the endpoint need?”

Agent engineering adds:

“Can the Agent reliably obtain these parameters from natural conversation?”

Suppose an API requires:

x
y
q
t

Technically valid.

Terrible Agent interface.

Compare:

latitude
longitude
forecastDate
timezone

The second interface has semantic meaning.

This matters because Generative Orchestration can use input names and descriptions to understand what information is required.

31. Missing Inputs

Suppose the Tool requires:

latitude

longitude

The user says:

“Tell me tomorrow’s weather.”

Something is missing:

Location.

The Agent can potentially recognize that required information isn’t available.

Conceptually:

Intent identified

↓

Tool selected

↓

Required inputs inspected

↓

Location missing

↓

Ask user

“Which location?”

↓

User provides location

↓

Continue plan

This is fundamentally different from manually creating every conversational branch.

32. Inputs Become Part of Conversation Design

This means API design now affects UX.

Traditionally:

API parameters

= developer concern

In an Agent:

API parameters

↓

Tool inputs

↓

Potential conversational questions

Therefore:

Tool schema becomes indirectly part of conversational design.

That is a major conceptual change.

33. Outputs Matter Equally

Imagine Open-Meteo returning hundreds of properties.

Does the Agent need all of them?

Maybe not.

If our Tool returns:

temperature

precipitationProbability

windSpeed

weatherCode

the Agent receives a concise structured result.

This is often preferable to dumping a huge JSON payload into the Agent.

Good Tool design considers both:

Inputs

and

Outputs.

34. Structured Outputs

Microsoft’s current Generative Orchestration guidance emphasizes well-defined inputs and outputs.

This gives us:

Tool

↓

Structured Output

↓

Planner

↓

Next step or response

Instead of:

Tool

↓

Huge arbitrary text blob

↓

LLM tries to understand everything

Structured outputs make orchestration more predictable.

35. Don’t Turn Everything into Text

Suppose the API returns:

temperature = 21.4
windSpeed = 32
precipitationProbability = 70

A poor integration might convert everything prematurely into:

“It is currently around 21 degrees and wind speed…”

A better Tool may preserve structured outputs.

Then the Agent can use:

temperature

windSpeed

precipitationProbability

independently.

Structured data preserves composability.

36. OpenAPI as an AI Interface Definition

This leads to a deeper interpretation.

Historically:

OpenAPI describes interfaces between software systems.

Now:

OpenAPI can also help describe interfaces between:

AI reasoning systems and deterministic software systems.

That is an important evolution.

We might think of it as:

Human language

↓

LLM semantic space

↓

Tool schema

↓

Software type system

↓

API

OpenAPI participates at the transition point.

37. Custom Connector vs REST API Tool

Copilot Studio currently gives us more than one integration path.

Custom Connector

API

↓

Custom Connector

↓

Connection

↓

Tool

↓

Agent

REST API Tool

API

↓

OpenAPI

↓

REST API Tool

↓

Agent

The two paths overlap but aren’t identical architecturally.

38. When Custom Connector Is Attractive

Use a Custom Connector when the API capability should be reusable across Power Platform.

For example:

Power Apps

Power Automate

Copilot Studio

Logic Apps scenarios

multiple solutions

multiple applications

Conceptually:

             Power Apps
                ↑
                |

API → Custom Connector → Power Automate
|
↓
Copilot Studio

The Connector becomes an integration asset.

39. When Direct REST API Is Attractive

A direct REST API Tool can be attractive when:

The capability is primarily Agent-specific.

You already have a suitable OpenAPI specification.

You want a relatively direct API-to-Agent integration.

You don’t require the same abstraction across several Power Platform workloads.

However, Microsoft’s current REST API Tool documentation for the Standard harness is still marked Preview, so production decisions should take that status into account.

40. Custom Connector as Enterprise Abstraction

Consider an internal API:

HR Employee Service

Instead of exposing raw technical operations everywhere:

GET /api/v3/persons/{id}/employment/current

we could expose a business-oriented connector action:

GetEmployeeEmploymentDetails

The abstraction becomes easier for:

Power Apps

Power Automate

Copilot Studio

and human maintainers.

This demonstrates an important principle:

Do not expose technical complexity to the Agent unless the Agent needs it.

41. Authentication

Once Tools interact with enterprise systems, authentication becomes critical.

Copilot Studio currently distinguishes scenarios in which Tools can operate with:

Agent author authentication

or

User authentication

depending on the Tool and scenario.

This distinction has major security implications.

42. Agent Author Authentication

Conceptually:

User

↓

Agent

↓

Tool

↓

Maker/Agent configured credentials

↓

API

The external system may see the Agent’s configured identity rather than the end user’s identity.

This can be acceptable for low-risk shared capabilities.

A public or low-risk weather service is an obvious conceptual example.

43. User Authentication

Now consider:

“Show me my confidential HR requests.”

The architecture should potentially be:

User

↓

Agent

↓

User Authentication

↓

Tool

↓

API

↓

Authorization evaluated for that user

This preserves user-specific security boundaries.

44. The Security Question

For every Tool ask:

Who is actually calling the API?

Not merely:

“Who is talking to the Agent?”

These are different questions.

User identity

may not equal

Connection identity.

This distinction is critical.

45. The Oversharing Risk

Imagine:

Maker has access to:

HR Site

Finance Site

Executive Site

The Agent uses maker-provided credentials.

An ordinary employee uses the Agent.

If Tool design and authorization are poor, the Agent could potentially become an unintended privilege bridge.

Microsoft specifically warns that maker-provided credentials can lead to oversharing because operations can run using permissions belonging to the maker rather than the end user.

Therefore authentication architecture must be designed deliberately.

46. Least Privilege for Tools

A Weather Tool doesn’t need SharePoint permissions.

A SharePoint ticket creation Tool doesn’t need tenant administration rights.

An HR lookup Tool shouldn’t automatically expose payroll administration.

The same security principle used everywhere else applies:

least privilege

An Agent does not justify broader permissions.

In fact, generative orchestration makes permission discipline even more important.

47. Read Tools vs Write Tools

Consider:

GetWeatherForecast

This is low-impact and read-only.

Now consider:

DeleteEmployeeRecord

The risk profile is completely different.

Tool classification should therefore include:

Read-only

Create

Update

Delete

Financial transaction

Communication

Approval

Administrative action

Sensitive-data access

This classification should influence Agent design.

48. Human Confirmation

For consequential operations, architecture might include:

User Request

↓

Agent

↓

Tool selected

↓

Parameters prepared

↓

Confirmation

↓

Execute Tool

This provides another boundary between:

AI interpretation

and

real-world side effects.

Not every GET needs confirmation.

A destructive DELETE probably deserves much stronger controls.

49. API Errors Must Become Agent Concepts

APIs fail.

Possible responses include:

400

401

403

404

429

500

Timeout

An Agent integration must understand that:

Tool execution

does not guarantee

Tool success.

The architecture therefore needs:

Agent

↓

Tool

↓

API

↓

Error

↓

Structured Tool Failure

↓

Agent

↓

Appropriate response

The Agent should not pretend the operation succeeded.

50. Example

Suppose:

User:

“Get tomorrow’s weather.”

Tool executes.

Open-Meteo is unavailable.

Bad Agent:

“Tomorrow will be sunny.”

Good Agent behavior:

The Tool failed, therefore current forecast data couldn’t be retrieved.

The distinction is critical.

Tool failure must not silently fall back to hallucination.

51. Observability

Enterprise Agent systems need observability.

We should eventually be able to investigate:

What did the user ask?

Which Tool was selected?

Why was that Tool relevant?

What inputs were supplied?

Which identity executed it?

What response was returned?

Did it fail?

What did the Agent finally tell the user?

Conceptually:

User

↓

Agent

↓

Plan

↓

Tool Call

↓

API

↓

Result

↓

Final Answer

Each boundary matters during troubleshooting.

52. Testing Tool Selection

Testing an Agent isn’t only:

“Did the API work?”

We must test:

Did the Agent select the correct Tool?

Did it avoid irrelevant Tools?

Did it collect missing inputs?

Did it transform inputs correctly?

Did it interpret outputs correctly?

Did it handle failures?

Did it respect authentication?

Did it avoid calling destructive Tools unnecessarily?

Agent testing is therefore broader than API testing.

53. Negative Tests

Suppose we have:

GetWeatherForecast

CreateSharePointRequest

SendEmail

Ask:

“What’s tomorrow’s weather?”

Expected:

GetWeatherForecast

Now:

“Create a request for a broken laptop.”

Expected:

CreateSharePointRequest

Now:

“Explain what rain is.”

Potentially:

No Tool required.

This last case matters.

An Agent shouldn’t call APIs simply because Tools exist.

54. Tool Economy

Every Tool should have a reason to exist.

Too many overlapping Tools can make orchestration harder.

Imagine:

GetWeather

RetrieveWeather

FindWeather

WeatherInformation

WeatherLookup

Their semantic boundaries overlap.

Better:

GetCurrentWeather

GetWeatherForecast

GetHistoricalWeather

Clear boundaries help both humans and orchestration.

55. Agent Instructions and Tools

OpenAPI tells the Agent what capability exists.

Instructions can provide behavioral guidance about how capabilities should be used.

For example:

Use the Weather Forecast Tool whenever the user asks for current or future weather information. Never invent current weather conditions from general model knowledge. If the Tool fails, clearly state that live weather data could not be retrieved.

Notice the separation:

OpenAPI:

What operation exists?

Instructions:

How should the Agent behave around that capability?

56. Instructions Should Not Reimplement Swagger

A common mistake would be putting this into Instructions:

Send GET to /v1/forecast, put latitude in the query string, longitude in the query string…

That belongs to the API contract.

Instructions should focus on behavior.

This gives us clean separation:

Swagger/OpenAPI

= technical contract

Instructions

= behavioral contract

57. Knowledge, Instructions and Tool Contract

We can now create a useful three-part model.

Knowledge

What information can I retrieve?

Instructions

How should I behave?

Tool Contract

What can I execute and what structured inputs/outputs exist?

These should not be mixed unnecessarily.

58. Four Architectural Layers

A mature Agent can be understood through four layers.

Layer 1 — Reasoning

LLM

Generative Orchestration

Intent

Planning

Layer 2 — Information

Knowledge

Retrieval

Grounding

Layer 3 — Capabilities

Tools

Topics

Flows

Connectors

REST APIs

MCP

Layer 4 — Enterprise Systems

SharePoint

Dataverse

Microsoft Graph

ERP

CRM

External APIs

Custom applications

The Agent sits above existing enterprise capabilities.

59. Where OpenAPI Lives

OpenAPI primarily sits between:

Capabilities

and

External Systems.

Conceptually:

Agent

↓

Tool

↓

OpenAPI Contract

↓

REST API

↓

System

It defines the boundary through which Agent reasoning reaches deterministic software.

60. REST API vs MCP

Another integration model becoming increasingly important is:

Model Context Protocol — MCP

Conceptually:

Direct REST Tool:

Agent

↓

REST Tool

↓

Specific API

MCP:

Agent

↓

MCP Server

↓

Tools / Resources

↓

Systems

MCP provides a standardized Agent-oriented protocol for exposing capabilities and resources.

This doesn’t make REST or OpenAPI obsolete.

Rather, it adds another abstraction option.

61. REST, Connectors, Flows and MCP

A useful architecture comparison is:

A good architect selects the simplest mechanism that satisfies the requirement.

62. Don’t Use an Agent for Everything

Imagine:

Every morning at 08:00 call Open-Meteo and save temperature in SharePoint.

Architecture:

Recurrence

↓

Weather API

↓

SharePoint

Power Automate is probably sufficient.

No Agent reasoning is required.

Now:

“I’m organizing an outdoor company event sometime next week. Compare the weather forecasts for three possible days, consider our corporate outdoor-event policy and explain the safest scheduling options.”

Now we have:

Natural language

Multiple information sources

Tool calls

Knowledge

Context

Reasoning

This is much more Agent-like.

63. The Value of the Agent Is Reasoning and Orchestration

An Agent shouldn’t be introduced merely because an API exists.

REST API already works.

Custom Connector already works.

Power Automate already works.

The Agent becomes valuable when we need capabilities such as:

Natural-language interaction

Intent interpretation

Dynamic Tool selection

Combining information

Multi-step planning

Contextual responses

Knowledge + Action orchestration

Therefore:

Agent ≠ API replacement

Agent = intelligent orchestration layer.

64. Open-Meteo as an Agent Laboratory

Open-Meteo gives us an excellent laboratory because we can progressively introduce concepts.

Stage 1:

REST API

Stage 2:

Swagger/OpenAPI

Stage 3:

Custom Connector

Stage 4:

Connection

Stage 5:

Copilot Studio Tool

Stage 6:

Tool descriptions

Stage 7:

Inputs and outputs

Stage 8:

Generative Orchestration

Stage 9:

Tool chaining

Stage 10:

Error handling

Then we can replace Open-Meteo with an authenticated enterprise API.

65. Moving Toward SharePoint

Eventually our architecture might become:

User:

“Create a site-access request because the weather prevented me from reaching the office.”

Agent

↓

Understand intent

↓

Retrieve corporate policy from SharePoint Knowledge

↓

Ground reasoning

↓

Determine request is appropriate

↓

Collect required information

↓

Call Tool

↓

Power Automate / Custom Connector

↓

SharePoint

↓

Create Item

↓

Return ID

↓

Agent

↓

Explain result

Now we have combined nearly everything we have been studying.

66. The Enterprise Agent Mental Model

A useful final architecture is:

                     USER
                       │
                       ▼
                Natural Language
                       │
                       ▼
                    AGENT
                       │
              ┌────────┴────────┐
              │                 │
         Instructions      Orchestration
                                │
              ┌─────────────────┼─────────────────┐
              │                 │                 │
              ▼                 ▼                 ▼
          Knowledge           Tools             Topics
              │                 │
              ▼                 ▼
          Retrieval         Connector
              │                 │
              ▼                 ▼
          Grounding          OpenAPI
                                │
                                ▼
                              REST
                                │
                                ▼
                       Enterprise System

This is much closer to a real enterprise Agent than the simplistic model:

User → Chatbot → Answer.

67. The Most Important Boundary

The central architectural lesson is the boundary between:

Probabilistic reasoning

and

deterministic execution

Above the boundary:

Natural language

Intent

LLM

Planning

Semantic routing

Below the boundary:

Types

Schemas

Authentication

Authorization

HTTP

APIs

Transactions

Business systems

OpenAPI helps define that boundary.

68. Why This Matters

Without a defined Tool contract, an Agent would effectively be asked:

“Figure out how to talk to this system.”

With OpenAPI we instead say:

“These are the capabilities you’re allowed to use.”

That is fundamentally better architecture.

It changes:

Unlimited improvisation

into:

Constrained capability selection.

69. The Agent Should Choose, Not Invent

A mature Agent should generally:

Choose among capabilities.

Collect required parameters.

Pass structured information.

Interpret structured results.

Compose the final response.

It should not invent:

Endpoints

Permissions

Business operations

API schemas

Authentication flows

That responsibility belongs to the system architecture.

70. Final Mental Model

We can summarize everything as:

Natural Language

↓

Intent

↓

Generative Orchestration

↓

Tool Selection

↓

OpenAPI Contract

↓

Structured Inputs

↓

Authentication / Connection

↓

REST API

↓

Deterministic Enterprise System

↓

Structured Outputs

↓

Agent Reasoning

↓

Natural Language Response

And the responsibilities become:

Conclusion

OpenAPI becomes considerably more interesting when studied from the perspective of AI Agents.

Traditionally, Swagger answered:

“How can one software application call another?”

In an Agent architecture, it also participates in answering:

“What deterministic capabilities can the AI safely and structurally invoke?”

That distinction is fundamental.

An LLM understands natural language.

A REST API understands structured requests.

OpenAPI helps define the contract between these worlds.

Copilot Studio’s Generative Orchestration can interpret the user’s intention and determine which available capability should participate in fulfilling it.

The Tool exposes that capability.

OpenAPI defines its technical interface.

Authentication determines who is allowed to execute it.

The API performs the deterministic operation.

The Agent interprets the result and continues the interaction.

Therefore:

LLM = Reasoning

Instructions = Behavior

Knowledge = Information

Grounding = Evidence

Orchestration = Planning and Selection

Tool = Capability

OpenAPI = Contract

Connection = Access

API = Execution

Enterprise System = Source of Truth / Business Operation

This is the architecture that transforms a chatbot into something much more interesting:

an Agent capable of reasoning over information while safely invoking deterministic enterprise capabilities.

Current Microsoft Documentation

Microsoft Learn — Extend your agent with tools from a REST API
https://learn.microsoft.com/en-us/microsoft-copilot-studio/agent-extend-action-rest-api

Microsoft Learn — Generative Orchestration guidance
https://learn.microsoft.com/en-us/microsoft-copilot-studio/guidance/generative-orchestration

Microsoft Learn — Use agent tools to extend, automate, and enhance agents
https://learn.microsoft.com/en-us/microsoft-copilot-studio/guidance/agent-tools

Microsoft Learn — Use connectors in Copilot Studio agents
https://learn.microsoft.com/en-us/microsoft-copilot-studio/copilot-ai-plugins

Microsoft Learn — Configure user authentication for tools
https://learn.microsoft.com/en-us/microsoft-copilot-studio/configure-enduser-authentication

Microsoft Learn — Add MCP tools and resources to an Agent
https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-components-to-agent

Open-Meteo API Documentation
https://open-meteo.com/en/docs