Adding Tools: Custom Connectors and REST APIs
Custom connectors and REST API tools for agent integration.
Giving your agent hands — not just a brain
Knowledge sources let your agent answer questions. Tools let your agent do things.
In the previous modules, you connected knowledge — the agent can search documents and look up data. But what about when the agent needs to create a shipping label, check a delivery status, or trigger a background check? That is where tools come in.
Copilot Studio gives you two ways to add tools that call external systems: custom connectors (you build a reusable connector from an OpenAPI spec) and REST API tools (you point the agent directly at an API endpoint). Both let the agent call external services — but they work differently and serve different purposes.
The critical three-way comparison
This table resolves the most confusing distinction in the exam. Topic HTTP requests, REST API tools, and custom connectors all call external APIs — but they are fundamentally different mechanisms.
| Feature | How it is triggered | Scope | Reusability | Auth configuration | When to use |
|---|---|---|---|---|---|
| Topic HTTP request (M10) | Runs inside a topic node — you explicitly place it in the flow | Single topic only — fires when that topic's flow reaches the HTTP node | Not reusable — copy/paste to use in another topic | Inline in the HTTP node (headers, query params) | One-off API calls within a specific conversation flow you control |
| REST API tool | Agent autonomously decides to call it based on the user's intent | Global (available to orchestrator across all topics) or agent-scoped | Reusable within the agent but not across agents without reconfiguration | Configured at the tool level (API key, OAuth, or none) | When the agent should autonomously decide to call an API based on conversation context |
| Custom connector | Agent autonomously invokes connector actions as tools | Shared across the Power Platform environment — usable by multiple agents and apps | Highly reusable — published to the connector gallery | Configured at the connector level with connection-level auth | When multiple agents or apps need the same API integration — build once, use everywhere |
Exam trap: 'the agent calls an API' is not enough information
If an exam question says “the agent calls an external API,” that alone does not tell you which mechanism is used. You need to know: Does the developer control when it fires (topic HTTP)? Does the orchestrator choose autonomously (REST API tool or custom connector)? Is it shared across agents (custom connector)? Read the scenario carefully for these clues.
Custom connectors: build once, use everywhere
A custom connector wraps an external API as a reusable Power Platform connector. Here is the workflow:
- Get the API’s OpenAPI spec (Swagger JSON/YAML). If the API does not have one, you can build the definition manually in the custom connector editor.
- Create the custom connector in the Power Platform maker portal — import the OpenAPI spec, configure the base URL, and define actions (each action maps to an API endpoint).
- Configure authentication — supported types: API key, OAuth 2.0 (authorization code or client credentials), Windows authentication, or no auth.
- Test the connector in the maker portal — verify each action returns expected data.
- Add to the agent — in Copilot Studio, add the custom connector as a tool. Select which actions to expose to the agent.
- Configure descriptions — the orchestrator uses the action descriptions to decide when to invoke the tool. Clear, specific descriptions are critical for correct autonomous invocation.
Why descriptions matter so much
When you add a custom connector as a tool, the agent’s orchestrator reads the action description to decide whether to call it. A vague description like “Gets data” will confuse the orchestrator. A precise description like “Retrieves the current delivery status for a shipment by tracking number” tells the orchestrator exactly when to use the tool. Poor descriptions are the number one cause of tools not firing or firing at the wrong time.
REST API tools: direct and fast
REST API tools skip the connector layer entirely. You configure the API call directly in Copilot Studio.
Configuration steps:
- In Copilot Studio, navigate to Tools and add a new REST API tool.
- Define the endpoint — URL, HTTP method (GET, POST, PUT, DELETE), headers, query parameters, and request body schema.
- Define the response schema — tell the agent what shape the JSON response will have so it can extract values.
- Configure authentication — API key (header or query param), OAuth 2.0, or managed identity.
- Set the scope — global (orchestrator can use it anytime) or restricted to specific topics.
- Write a clear description — same as custom connectors, the orchestrator uses this to decide when to call the API.
Global vs topic-scoped REST API tools:
| Scope | Behaviour | Use when |
|---|---|---|
| Global | Available to the orchestrator across all conversations. The agent autonomously decides when to call it. | The API is broadly useful — weather, exchange rates, shipping status |
| Topic-scoped | Only available within specific topics. The orchestrator only considers it during those topics. | The API is relevant only in specific conversation flows |
Scenario: Dev creates a delivery tracking connector
Dev is the Power Platform developer at a logistics company. The internal shipping system exposes a REST API for tracking deliveries. Dev needs the customer service agent to look up delivery status automatically when customers ask “Where is my package?”
Dev has a choice: custom connector or REST API tool?
The shipping API is used by four different agents (customer service, warehouse ops, returns, and partner portal). Dev chooses a custom connector — build once, use in all four agents. He imports the OpenAPI spec from the shipping team, configures OAuth 2.0 client credentials (the agent authenticates as a service account), and publishes the connector. Then he adds it to the customer service agent with the description: “Retrieves real-time delivery status, estimated arrival date, and carrier details for a shipment by tracking number.”
A customer asks: “Where is order #SH-2024-55891?” The orchestrator reads the tool description, matches the intent, calls the connector action with the tracking number, and returns: “Your order is currently in transit via FedEx. Estimated delivery: Thursday, May 8.”
Scenario: Priya registers a background screening API
Priya at AgentForge needs her recruitment agent to trigger background checks on shortlisted candidates. The screening vendor provides a REST API but no OpenAPI spec, and only AgentForge’s recruitment agent uses it.
Priya chooses a REST API tool — no need for the overhead of a custom connector since only one agent uses this API. She configures a POST endpoint to /api/v2/screening/initiate, adds the API key as a header, defines the request body (candidate name, email, consent reference), and maps the response schema (screening ID, estimated completion date, status).
She scopes the tool to the “Candidate Shortlist” topic only — the agent should only trigger screening during the shortlisting flow, not randomly in general conversation. When Priya’s team shortlists a candidate, the agent asks: “Shall I initiate the background check for this candidate?” On confirmation, it calls the API and returns: “Background check initiated. Reference: SCR-2024-1847. Expected completion: 3 business days.”
Dev's logistics company has four agents that all need to call the same shipping API. What should Dev build?
Priya configures a REST API tool but the agent never calls it, even when users ask relevant questions. What is the most likely cause?
An exam question describes a scenario where the developer places an HTTP call inside a topic flow at a specific step. Which mechanism is this?