10.4 Add REST APIs to an Agent

Why REST API tools matter on AB-620

Add REST APIs to an agent completes the tools quartet with a first-class path for OpenAPI-described HTTP services. Where custom connectors emphasize Power Platform connector lifecycle, the REST API tool wizard focuses on turning a specification into one or more agent tools quickly—still with authentication, descriptions, and solution awareness.

What you must provide

Microsoft documents three essentials to connect a REST API:

1. An OpenAPI specification defining functions and available actions.
2. Authentication type and details so users or the agent can access the API.
3. Descriptions that help the language model decide when to invoke each operation.

You can add REST API tools to custom agents and to agents that extend Microsoft 365 Copilot experiences; the add process is the same at a high level.

Specification rule: create REST API tools from an OpenAPI v2 specification because of how Power Platform processes API specs. If you submit v3, creation automatically translates it to v2. Prefer cleaning the spec before upload so translation surprises (unsupported constructs) do not appear only at runtime.

End-to-end wizard steps

1) Start REST API tool creation

From the agent Overview Tools section or Tools tab: Add tool → New tool → REST API.

2) Specification, description, and solution

Upload the OpenAPI JSON (drag-and-drop or browse). Verify detected details.

On API plugin details:

• Description is prefilled from the spec but is often too thin for orchestration. Expand with verbs and synonyms. Example: weak — “A simple service to manage tickets.” Stronger — “Get, retrieve, find, and display existing tickets from SunnyADO; update and manage ticket fields to improve records.”
• Solution — select an environment solution for ALM. Preferred/default solutions may auto-select; if left blank, the platform can create a solution using the action name and default publisher. Storing actions in solutions makes movement across environments tractable. Prefer a custom solution over relying only on default CDS solutions when managing enterprise ALM.

3) Authentication details

OAuth lets users grant permissions without sharing their primary credentials with the agent. API key is simpler but weaker for per-user enterprise authorization. None is rare in production LOB systems.

4) Select and configure tools (operations)

A REST API exposes many endpoint + method combinations (GET/POST/PUT/DELETE…). You often must not enable every operation. Example: allow create and read, but not delete, for a helpdesk agent.

For each selected tool:

1. Open Configure your tool.
2. Set Tool name and Tool description (specific enough for model routing).
3. Review parameters page — inputs and outputs come from the spec; you generally cannot change schemas here, but you must supply missing descriptions. Blank descriptions block progress; paste the parameter name as a last resort, but prefer human meaning (“work item id from Azure Boards”).
4. Return to selection list; add more operations; continue when the agent’s surface area is correct.

5) Review, publish, connect, attach

Review summary → publish (wait for completion) → Create connection → back on Add tool, filter REST API → for each operation, select connection (or create) → Add and configure.

Each selected API operation appears as its own tool entry. Use search to find them in large agents.

Descriptions as orchestration contracts

Generative orchestration selects tools using names, descriptions, conversation context, and available inputs/outputs. For REST tools:

• API-level description orients the overall system.
• Operation-level description disambiguates GET list vs GET by id vs POST create.
• Parameter descriptions improve dynamic fill and reduce wrong ID formats.

After attachment, still use the common tool pages:

• Dynamic vs custom input fill
• Ask before running for high-impact POSTs
• Completion behavior (model-written response vs fixed template)
• Enable/disable dynamic decision so some operations stay topic-only

Error handling and operational readiness

REST tools fail for reasons that appear on exams and in labs:

Maker practice: test with representative prompts in agent test chat, inspect Activity for which tool was chosen, and refine descriptions before blaming the API. For explicit process control, call the REST tool from a topic Action after validating inputs in dialogue.

Scenario: SunnyADO ticket API (exam-style)

SunnyADO exposes OpenAPI for tickets. Product wants employees to list and update tickets in Teams via an agent, but not delete tickets.

1. Export OpenAPI; if v3, accept translation to v2 or publish a cleaned v2.
2. New tool → REST API → upload → rewrite description with retrieve/update synonyms.
3. Place in Fabrikam Agents solution for ALM.
4. Choose OAuth 2.0 against the corporate IdP so each employee’s ticket scope is honored.
5. Select GET /tickets, GET /tickets/{id}, PATCH /tickets/{id} only—omit DELETE.
6. Fill every blank parameter description (id → “Unique SunnyADO ticket identifier”).
7. Publish, create connections, Add and configure each operation.
8. Set ask-before-run on PATCH; leave GETs automatic.
9. Test: “Show my open tickets” should hit list; “Close ticket 1234” should confirm then PATCH; “Delete ticket 1234” should not find a delete tool.

REST vs custom connector vs MCP vs computer use (final comparison)

Exam checklist

1. List the three requirements: OpenAPI, auth, descriptions.
2. Remember v2 processing and v3 auto-translation.
3. Walk the five wizard stages without skipping parameter descriptions.
4. Choose auth scheme from scenario cues (public vs key vs user OAuth).
5. Subset operations intentionally for least privilege.
6. After publish, still create connections and attach tools; then tune orchestration descriptions and completion behavior.
7. Diagnose failures by layer: spec, auth, connection, orchestration selection, HTTP, policy.