
The built-in connectors cover a lot, but the moment you need to talk to an internal REST API from a Copilot Studio agent, you need a custom connector. This walkthrough builds a working copilot studio custom connector end to end, from the OpenAPI definition to the agent calling it as a tool with structured output the LLM can actually reason about.
The result: an agent that calls an internal API, gets back a typed JSON response, and uses it in the conversation without guessing.
Step 1: Get your API contract straight before you open the portal
Do not start in Power Apps. Start with the API spec. You need an OpenAPI 2.0 (Swagger) file or a clear list of endpoints, methods, query parameters, request bodies, and response schemas.
If your API returns 200 OK with an empty body on success, fix that first. An agent needs structured output to evaluate what happened. I learned this the hard way building agentic flows: returning {"status":"done"} is not enough. Return the actual record, the actual ID, the actual changed fields.
Make sure every response has a defined schema. type: object with named properties. No loose additionalProperties: true dumps. The agent reads the schema to decide how to use the result.
Step 2: Create the custom connector in the Power Platform maker portal
Go to make.powerautomate.com, pick the right environment (this matters, custom connectors are environment-scoped), then Data, Custom connectors, New custom connector, Import an OpenAPI file.
Upload your Swagger file. Fill in:
- Host:
api.yourdomain.com(no https prefix) - Base URL:
/v1or whatever your API uses - Scheme: HTTPS only. Do not ship HTTP.
If you do not have a Swagger file, use the blank template and define operations manually. It is slower but gives you full control over operation IDs and summaries, which the agent uses to pick the right tool.
Step 3: Configure authentication properly
For internal enterprise APIs, OAuth 2.0 with Microsoft Entra ID is the only option I would ship. API key auth works for prototypes and falls apart the moment you need per-user identity in the agent. The same principle applies when thinking about Power Platform governance that does not kill adoption — authentication decisions made at the connector level affect every maker and every environment downstream.
In the Security tab, pick OAuth 2.0, Identity Provider Azure Active Directory, and fill in:
- Client ID: from your app registration
- Client secret: from the same registration
- Resource URL: the App ID URI of the API, for example
api://your-api-app-id - Scope: the scope you exposed on the API app registration, e.g.
access_as_user
Save, then copy the Redirect URL Power Platform generates and add it to your Entra app registration’s redirect URIs. Skip this and you will get AADSTS50011 on every connection attempt.
Step 4: Define operations with names the LLM can understand
This is where most connectors fail as agent tools. The operation summary and description are not metadata. They are the prompt the LLM uses to pick the tool.
Bad: GetData. Good: Get order details by order ID.
For each operation set:
- Summary: what the operation does, in plain English
- Description: when to use it, what it returns
- Operation ID: camelCase, descriptive, like
getOrderById - Parameter descriptions: every parameter, including required vs optional
Test each operation in the Test tab before moving on. If it does not return clean JSON here, it will not work in the agent.
Step 5: Add the connector to a Copilot Studio agent as a tool
Open your agent in Copilot Studio. Go to Tools, Add a tool, then pick Connector and find your custom connector. Microsoft’s docs on connector tools in Copilot Studio cover the UI changes if anything looks different in your tenant. If you are still getting oriented with the platform itself, If You Are Starting Copilot Studio in 2026 Skip the Chatbot Tutorials is worth reading before you wire up your first tool.
For each operation you want to expose:
- Review the auto-generated tool description. Rewrite it if it is vague.
- Mark inputs as
Dynamically fill with AIfor parameters the LLM should infer from conversation, orCustom valuefor static config. - Set the connection. For testing, use your own. For production, configure end-user authentication so each user authenticates with their own identity.
Step 6: Test it end to end with realistic input
In the Test pane, do not type the obvious phrasing. Type how a real user would ask. Watch the activity map. You want to see the tool getting picked, the parameters extracted correctly, the response coming back as structured JSON, and the agent using specific values from that JSON in its reply.
If the agent paraphrases instead of citing values, your response schema is too loose or the tool description is misleading. Tighten both.
The final state and one common pitfall
You now have a custom connector calling an authenticated internal API, registered as a tool the agent can invoke based on conversation context, returning structured data the LLM uses in its response.
The pitfall to watch for: connection caching across environments. A connector that works in your dev environment will not auto-promote. You need to export the solution, import it into the next environment, and recreate the connection reference there. Skip that and your ALM pipeline will fail in ways that look like auth bugs but are really environment scoping. If your setup involves agents talking to external systems across multiple environments, the same scoping problems come up in Power Platform Agents Talking to GitHub Sounds Simple Until You Hit Enterprise Environment Sprawl.
Frequently Asked Questions
How do I create a custom connector in Copilot Studio?
To build a Copilot Studio custom connector, start by preparing an OpenAPI 2.0 (Swagger) file that defines your API endpoints, parameters, and response schemas. Then go to make.powerautomate.com, navigate to Data, Custom Connectors, and import your Swagger file. From there you configure authentication, define your operations, and connect the connector to your Copilot Studio agent as a tool.
What is the best authentication method for a custom connector in Power Platform?
OAuth 2.0 with Microsoft Entra ID is the recommended approach for enterprise APIs, as API key authentication does not support per-user identity. Authentication choices made at the connector level affect every maker and environment that uses it downstream, so it is worth getting right from the start.
Why does my Copilot Studio agent not understand the API response correctly?
If your API returns a vague or empty response body, the agent has nothing structured to reason about. Every response should include a defined schema with named properties so the agent can interpret the result and decide how to use it in the conversation.
When should I build a custom connector instead of using a built-in one?
You need a custom connector when your Copilot Studio agent needs to call an internal or proprietary REST API that is not covered by the existing built-in connectors. If your use case involves company-specific data or internal services, a custom connector is the right path.








