API Actions in Agents

Overview

Not every API has a pre-built connector, and not every integration needs one. Sometimes you need a quick, direct connection between your agent and a REST endpoint—a case status API, a lookup service, or an internal agency system.

API actions in Copilot Studio let your agent call REST endpoints directly. You provide an OpenAPI specification, Copilot Studio generates the action, and your agent can call the API at runtime. This video walks you through building API actions, parsing responses, configuring authentication for government clouds, and handling errors.

What You’ll Learn

• API actions vs. connectors: When to use plugin actions instead of connectors
• Creating actions: Building HTTP request actions from OpenAPI specs
• Parsing responses: Working with simple, nested, and array responses
• Authentication and errors: Securing API calls and handling failures gracefully

Script

Hook: Your agent needs to call an API

Not every API has a connector. Not every integration justifies building one.

Your agency has a case management API. There is no connector in the gallery for it. You could build a custom connector—but you just need to call two endpoints. Do you really need to go through the full connector creation process?

API actions in Copilot Studio let your agent call REST endpoints directly. You define the request using an OpenAPI specification, parse the response, and use the data in your conversation. No connector required.

In the next twelve minutes, you will build API actions that connect your agent to external services, handle authentication for government clouds, and manage errors gracefully.

What API actions are

Copilot Studio offers two ways to call external services: connector actions and plugin actions. Connector actions use pre-built or custom connectors—the approach covered in earlier videos. Plugin actions define API calls directly using OpenAPI specifications. They are lighter weight and faster to set up.

Use API actions when you need a quick integration without the overhead of building a full custom connector. They are ideal when you need fine-grained control over the request, when you are prototyping an integration before committing to a custom connector, or when you only need to call one or two endpoints on a service.

Here is how API actions work. You provide an OpenAPI specification—also known as a Swagger file—that describes the API’s endpoints, parameters, and response schemas. Copilot Studio reads the spec and generates actions from it. Each operation in the spec becomes an action you can add to your agent’s topics. At runtime, the agent calls the API endpoint and returns the response data to the conversation.

In government environments, API actions follow the same rules as connectors. The API endpoint must be reachable from your cloud boundary. Authentication must be configured for government identity providers. And API actions are subject to the same DLP and compliance policies as connectors.

Creating HTTP request actions

Start with your OpenAPI specification. If the API you need to call already has an OpenAPI spec, you are ahead. If not, you will need to write one. The spec defines the API endpoint, the HTTP method (GET, POST, PUT, DELETE), the path, request parameters (path, query, header, body), and the response schema with all fields your agent needs to use. Include descriptions for every parameter and field—these descriptions appear in the Copilot Studio authoring UI and help other developers understand how to use the action.

To add an API action to your agent, open Copilot Studio and go to Actions. Select “Add an action” and choose “Plugin action.” Upload your OpenAPI specification file or provide a URL where the spec is hosted. Copilot Studio reads the spec and generates actions from each operation defined in it.

Configure each action. Set the base URL for your API—this is the root address that path parameters are appended to. Map dynamic values to identify which parameters come from the conversation—for example, a case ID that the user provided. Set static values for parameters that do not change—API version headers, fixed query parameters, or content type headers. In government environments, the base URL must point to an endpoint within your cloud boundary or accessible through an approved gateway.

Here is a concrete example. Your agency has a case management API. The OpenAPI spec defines a GET /cases/{caseId} endpoint with caseId as a path parameter. The response schema includes status, assignedTo, lastUpdated, and priority fields. You upload the spec, Copilot Studio generates a GetCase action. In your topic, you collect the case ID from the user with a question node, pass it to the GetCase action, and display the result: “Case CS-2024-00145 is Open, assigned to Maria Torres, priority High, last updated February 3.”

A single OpenAPI file can define multiple endpoints, and each becomes a separate action. One spec covering GetCase, CreateCase, and UpdateCase gives you three actions from a single file upload.

Parsing API responses

When the API action executes, Copilot Studio parses the response using the schema defined in your OpenAPI spec. Each field in the schema becomes an output variable that you can use in subsequent topic nodes.

For simple, flat JSON responses, parsing is straightforward. If the API returns something like status as “Open” and assignedTo as “Maria Torres,” each field maps directly to a variable. You reference them in message nodes, condition nodes, and other actions.

For nested objects, you need to define the full nested structure in your OpenAPI spec. If the response includes an address object with city and state fields inside it, your spec must describe that nesting. You then access nested properties using dot notation or Power Fx expressions—response.address.city gives you the city value.

API responses often contain arrays—a list of cases, a list of search results, a list of open tickets. Copilot Studio can work with arrays, but handling them requires some care. You can iterate through arrays using adaptive cards to display a list, or format the array into readable text within the topic. For more complex array processing, use a Power Automate flow: call the API from the flow, process the array with Select and Join actions, and return formatted text to the agent.

Always handle missing or null fields defensively. If a field might not be present in every response, check for empty values before displaying them. Use condition nodes: if the status field is blank, show “Status not available” instead of an empty space or a broken variable reference. Defensive parsing prevents broken messages that confuse users.

For government data, only extract the fields the user is authorized to see. If the API response includes sensitive fields—PII, classification markings, financial data—filter what your agent displays based on the user’s role or clearance level. Log what data was returned for compliance auditing.

Handling authentication

Most APIs in government environments require authentication. API actions in Copilot Studio support several methods.

API Key authentication is the simplest. You specify a header name—typically “X-API-Key” or “Authorization”—and provide the key value. The key is sent with every request. In government environments, rotate API keys per your agency’s credential management policy and store them securely. Never embed the key directly in the OpenAPI specification file.

OAuth 2.0 authentication is the most common method for modern APIs. Register an application in Microsoft Entra ID. Configure the action with the client ID, client secret, authorization URL, and token URL from the app registration. The critical detail for government clouds is using the correct endpoints. For GCC, the authorization and token URLs use login.microsoftonline.com with your GCC tenant. For GCC High, use login.microsoftonline.us. For DoD, use login.microsoftonline.us with your DoD tenant. Getting these endpoints wrong is one of the most common authentication failures in government environments.

Choose between delegated permissions—where each user authenticates individually, creating per-user connections—and application permissions, where a service account authenticates once for all users. Delegated permissions create better audit trails because every API call is tied to a specific user.

Microsoft Entra ID authentication provides a simplified setup when the API is registered in the same tenant as your Copilot Studio environment. You provide the app ID URI as the resource, and Power Platform handles token acquisition. This is the recommended approach for APIs hosted in Azure within your government tenant.

Each authentication configuration creates a connection in Power Platform. Per-user connections require each user to authenticate the first time they trigger the action. Shared connections use service account credentials for all users. In government environments, prefer per-user connections for accountability and audit trails. Use shared connections only when there is no user context for the API call.

When troubleshooting authentication, check these common issues. A 401 error usually means the token URL or scopes do not match what the API expects. Token expiration is handled automatically by Power Platform for OAuth—it refreshes tokens as needed. Consent issues arise when the app registration has not received admin consent in your tenant. Cross-tenant API calls may require additional trust configuration in government clouds.

Error handling for API calls

APIs fail. Networks have transient issues. Services go down for maintenance. Your agent needs to handle these situations without leaving the user stranded.

The most common API errors fall into a few categories. A 400 Bad Request means the input was invalid—validate user inputs before making the API call. A 401 Unauthorized indicates an authentication failure. A 403 Forbidden means the authenticated user does not have permission. A 404 Not Found means the requested resource does not exist. A 429 Too Many Requests means you have been throttled. A 500 Internal Server Error means something went wrong on the server side.

Handle these in your topic with condition nodes after the API action. Check the response status and route to different messages based on the error. For a 404: “I could not find a case with that ID. Please check the number and try again.” For a 500: “The system is temporarily unavailable. Please try again in a few minutes or contact the help desk.”

For transient errors like 429 and 500, offer the user a retry option. Add a quick reply button: “Would you like me to try again?” If they select yes, loop back to the action node. For more sophisticated retry logic—automatic retries with exponential backoff—wrap the API call in a Power Automate flow that handles retries before returning the result to the agent.

Monitor API action failures in production. Log failures for operational visibility. Set up alerts when failure rates exceed a threshold. For government teams, integrate these alerts with your existing incident management process so API outages are tracked and resolved through your standard workflow.

Close: API actions in practice

Here is what you learned. API actions let your agent call REST endpoints directly using OpenAPI specifications—no connector required. Response parsing maps JSON fields from the API to topic variables you can use in messages and conditions. Authentication supports API keys, OAuth 2.0, and Entra ID, with government-specific endpoints for GCC, GCC High, and DoD. Error handling uses condition nodes to route conversations gracefully when API calls fail.

When should you use API actions versus custom connectors? Use API actions for quick integrations, prototyping, and simple APIs where you only need a few operations. Use custom connectors when you need the integration to be reusable across multiple agents and Power Automate flows, or when you want to share it with your development team.

Three things to do next. Find an API your team uses regularly and obtain or write its OpenAPI specification. Create a plugin action in a test agent and verify the round trip—user input to API call to response display. Test authentication using your government cloud’s Entra ID endpoints to confirm everything works within your cloud boundary.

API actions give your agent direct access to any REST service. No connector required—just an OpenAPI spec and a conversation.

Sources & References

• Plugin actions in Copilot Studio — Official documentation on creating and configuring plugin actions, including OpenAPI-based API actions
• Use connectors in Copilot Studio — Connector and action architecture documentation, including how actions interact with topics
• Copilot Studio documentation — Main documentation hub for agent building, topics, and platform capabilities
• Microsoft Entra ID OAuth 2.0 authorization code flow — OAuth 2.0 flow documentation for configuring API authentication