Write effective instructions for declarative agents with API plugins

Declarative agents tailor Microsoft 365 Copilot to meet the specific needs of an organization. When you build declarative agents with Microsoft 365 Agents Toolkit (an evolution of Teams Toolkit), you can add skills to your agent via API plugins. API plugins enable your agent to query and interact with an organization's data via APIs.

This article describes the agent architecture and provides best practices for writing instructions for declarative agents that include API plugins.

Main components of declarative agents with API plugins

Declarative agents that call API plugins include several components that ensure effective integration and functionality. Understanding this architecture will help you design your agent effectively. The architecture includes the following components:

• Application manifest - Describes how your app is configured and references declarative agent manifest.
• Declarative agent manifest - Defines the agent's configuration, including instructions, capabilities, conversation starters, and actions. References the plugin manifest.
• Plugin manifest - Describes the plugin configuration, including available functions and a reference to the OpenAPI specification.
• OpenAPI specification - Provides detailed definitions of API endpoints, including paths, parameters, request and response formats, and authentication.

Together, these files define the agent's behavior and how it interacts with the underlying API.

For more information about API plugins, see:

• API plugins for Microsoft 365 Copilot
• How to make an OpenAPI document effective in extending Copilot capabilities

Function mapping in the plugin manifest

In the plugin manifest, each function must map to a corresponding operationId in the OpenAPI specification. This ensures that when the agent invokes a function (for example, createTask), the agent knows which API endpoint to call.

The following examples show the mapping in the plugin manifest and the mapped function in the OpenAPI spec.

"functions": [
  {
    "name": "createTask",
    "description": "Creates a new task in the specified task list."
  }
]

paths:
  /me/todo/lists/{listId}/tasks:
    post:
      operationId: createTask
      summary: Create a new task
      description: Creates a new task in the specified task list.
      parameters:

Best practices for agent instructions

Writing effective instructions is essential to ensuring that declarative agents with API plugins are successful. To optimize your agent, apply the correct function mapping, use chaining to enable richer interactions, and iteratively test and refine your agent's behavior.

Apply the following best practices when writing instructions for declarative agents with API plugins:

• Avoid ambiguous or negative instructions. Contrasting or negative instructions can introduce ambiguity and confuse the model. Focus on defining valid use cases with positive examples. If it's important to distinguish between valid and invalid queries, provide clear criteria and examples that define the expected agent response for each.
• Use examples Provide clear examples to guide agent behavior. For example:

User input: What's the weather in Prague? Agent call: getWeather(___location="Prague") User input: "Do I need an umbrella tomorrow?" Agent call: getWeather(___location=user_location, forecast="tomorrow")

• Review and test the instructions. Test instructions in various scenarios to verify that the agent makes the correct function calls. If in testing you find that the agent invokes functions unexpectedly, revise the function description in the OpenAPI specification and clarify the agent instructions to improve intent mapping.

• Design instructions for multi-turn conversations. When you integrate API plugins, design your instructions for the agent to handle multi-turn conversations.

For example, if the function requires multiple parameters, in addition to defining the required parameters in the OpenAPI spec, instruct the agent to collect all the parameters before making the API call. This ensures that the agent collects all required information in a logical sequence.

The following example shows how to instruct a weather agent for multi-turn conversations and the agent flow that results.

For general best practices for agent instructions, see Write effective instructions.

Chaining function calls in API plugins

Chaining function calls allows declarative agents to combine multiple API actions in one seamless flow. The following sections describe common patterns and how to write instructions for each.

Chaining function calls with output as input parameter

Use the result of one API call as an input for another. This is useful when the result of the first function is needed to perform the second function. This can work across plugins.

In the following example, a declarative agent with Weather API and To-do API creates a to-do task with data from the weather forecast.

Chaining based on conversation history within one agent

When you use chaining based on conversation history, the agent uses prior responses to handle follow-up actions. This approach uses the conversation history to maintain context.

In the following example, an agent deletes a to-do by name.

Chaining with SharePoint knowledge

Chaining API calls allows an agent to combine knowledge sources and actions to design more complex workflows.

In the following example, an agent retrieves project status data from SharePoint, and creates corresponding tasks in Microsoft To-Do for tracking.

Chaining with code interpreter

It is also possible to chain API calls and integrate additional capabilities, such as a code interpreter. This allows an agent to process API outputs dynamically to enable more advanced workflows.

In the following example, an agent creates a chart based on the data in to-do tasks.

This example also runs multiple actions at once. This is useful initiating a series of related actions that don't require multiple user inputs.

Related content

• Build a declarative agent with Visual Studio Code
• API plugins for Microsoft 365 Copilot