Add an agent node to a workflow (preview)

You can either pick an existing published agent or build a brand-new agent directly inside the node without leaving the workflow designer. Inline agents are the fastest way to add AI to a workflow. Give the node an instruction, optionally attach tools and knowledge, and you're done.

The agent node lets a flow hand a step over to an AI agent that can reason, call tools, and pull from knowledge sources before returning a result. Use it whenever a step needs judgment, multi-step orchestration, or information from outside the flow itself.

By using the agent node, you can:

• Call an existing agent.
• Give the agent a natural-language instruction, including dynamic content from earlier steps.
• Equip the agent with tools (Model Context Protocol (MCP) servers and connectors) so it can take action.
• Ground the agent in knowledge (SharePoint sites, public websites) so it can answer from your content.
• Use the agent's response in later steps of the flow.

Add an agent node

1. In Copilot Studio, go to Workflows and open an existing workflow, or create a new one.

   • New workflow: You land on the designer to configure a trigger.
   • Existing workflow: Open the workflow and go to the Build tab.

2. Select the Agent icon on the Add panel. The configuration panel opens for the agent node.

Choose an existing agent for the agent node

In the agent node editor, under Agent, select one of two options:

• An existing agent: Select a published agent from a list. The agent runs with whatever instructions, tools, and knowledge it was already configured with.
• New agent for this workflow: Build an inline agent scoped to this workflow. The agent's instructions, tools, knowledge, and output shape are configured in the node itself and travel with the workflow. Use this option when the agent's job is specific to this automation and you don't need to share it elsewhere.

The next section of this article focuses on configuring a new inline agent. If you select an existing agent, skip to Send a message to the agent.

Configure a new agent for the agent node

When you choose New agent for this workflow, the configuration panel expands so you can shape the agent in place.

Instructions

For an inline agent, the Instructions field serves as both the agent's job description and the per-run prompt. There's no separate Message field. Write what the agent should do in plain language, and include dynamic content from earlier steps to provide the data for this run.

Be specific about the task, the inputs the agent can expect, and the format of the response you want back. Clearer instructions mean more reliable runs.

For example, if the workflow trigger is When a new email arrives, your instructions might read: Read the email below and decide whether it's a sales lead, a support request, or something else. Reply with a single word. followed by the Subject and Body variables from the trigger.

To pick the model that powers the agent, use the model dropdown in the instructions box. Select a more capable model when the task involves multistep reasoning or careful interpretation. Select a faster model when the task is simple and runs at high volume.

Work IQ

Turn on Work IQ to let the agent use the running user's recent work activity, including mail, Teams, calendar, OneDrive, and SharePoint context, to ground its responses. This context is helpful when the workflow acts on behalf of a person and personal context makes the answer better.

Tools

Tools give the agent the ability to do actions such as send a message, query a record, run a search, or call an API. Without tools, the agent can only read and reason. With tools, it can also act.

To attach a tool:

1. In the Tools section, select the plus sign (+).

2. In Add tool, browse or search for the tool you want.

3. Select the tool to add it. You can add multiple tools to a single agent.

You can attach two kinds of tools:

• Model Context Protocol (MCP) servers: Prebuilt servers that expose a curated set of capabilities.
• Connectors: Any Power Platform connector action.

The agent decides at run time which of its attached tools to call, in what order, and with what arguments. You don't have to wire tools together.

Knowledge

Knowledge gives the agent something to read. When you ask the agent a question, it can ground its answer in the sources you attach instead of relying only on what the model already knows.

To attach a knowledge source:

1. In the Knowledge section, select the plus sign (+).

2. In Add knowledge, choose the source type:

   • Public websites: Index one or more public URLs so the agent can cite content from those sites.
   • SharePoint: Connect to a SharePoint site, library, or specific document so the agent can answer from internal content.

3. Provide the URL, and then save.

Attach knowledge whenever the right answer depends on content the model wasn't trained on, like internal policies, product specifications, customer agreements, or the latest pricing page on your website.

Output

Use the Output dropdown to control the shape of what the agent returns. The shape determines how downstream workflow steps consume the result.

When you pick a structured output, each field becomes its own dynamic-content token that downstream actions can reference directly.

Send a message to the agent

When you select an existing agent, the node shows a Message field. Use this field to tell the agent what to do for this run. The agent's instructions, tools, and knowledge are already set on the published agent.

In the Message field, write the prompt for this run. Use the dynamic content picker to insert tokens from earlier steps so the agent reasons over real run-time data. For example, in a workflow that triggers when a calendar event is created, the message might be Prepare a brief for followed by the Required attendees variable.

Request human assistance when unsure

Turn on Request human assistance when unsure to let the agent escalate when it isn't confident enough to act on its own. The agent emails the connection owner for input and waits for a reply before continuing.

Turn on this setting for high-stakes decisions where being wrong is more expensive than being slow, such as exception handling on financial transactions, edge-case approvals, or judgment calls on customer escalations.

Use the agent response in your workflow

When the agent node runs, the workflow waits for the agent to complete its task. The agent response then becomes available as dynamic content that you can use in any subsequent step.

To use the agent response in a downstream action:

1. Select the next action where you want to use the result.

2. Open the dynamic content picker on the field you want to fill.

3. Pick the output from the Agent step:

   • Text response output: A single agent response variable.
   • Structured or Custom structured output: One variable per field you defined.

Common patterns:

• Insert a text response into an email body, Teams message, or document.
• Branch the workflow on a structured field such as priority == "high".
• Write structured fields to Dataverse, Excel, or a SharePoint list.

Test and evaluate an agent node

After you configure an agent node, test it to verify that it behaves as expected before you publish your workflow. Testing lets you validate the agent's instructions, tools, knowledge sources, inputs, and outputs in isolation without running the entire workflow.

Evaluations build on the results of a test run and help you assess the quality of the generated response. Together, testing and evaluations support an iterative development workflow: Configure → Test → Evaluate → Improve.

Test an agent node

Use the Test pane in the agent's side panel to run the agent node and inspect its output.

1. Select the agent node to open its property side panel.

2. Select the Test tab.

3. Enter inputs manually, or use inputs from a previous workflow run.

4. Select Run test.

The test run executes the agent by using its current configuration and displays the generated output. Testing helps verify that the agent runs successfully and produces the type of response you expect. After generating a test result, use evaluations to assess the quality of that response and determine how well it meets your expectations and requirements.

Evaluate an agent node

After a successful test run, evaluate the response by using test methods.

A test method lets you describe, in natural language, what a good response should look like (and what not). During evaluation, the agent's output is assessed against these criteria to help determine whether it achieved the intended outcome. Test methods let you assess criteria such as:

• Whether the response answers the user's request.
• Whether the correct tools were used.
• Whether the output follows an expected format or schema.
• Whether the response aligns with the intended behavior of the agent.

Before you can run an evaluation, you must complete a test run and create at least one test method. You can create test methods manually or generate them automatically by selecting Auto generate. AI-generated test methods are based on the agent's instructions and configured tools and can help you get started more quickly with evaluation.

If you have multiple test methods, use the check boxes next to each test method to control which ones are included in the evaluation run. Clear a check box to temporarily exclude a test method without deleting it.

To delete a test method, open the modal evaluation experience by selecting the icon next to the Run evaluation button in the upper-right corner of the Evaluate pane. From there, select the test method you want to remove and delete it.

To evaluate a test result:

1. Run a test for the agent node.

2. Select Evaluate.

3. Create a grader or select an existing grader.

4. Select Run evaluation.

For each grader, the evaluation returns:

• A Pass or Fail result.
• Evidence or reasoning that explains the result.
• In case of a failed result, you might get AI-generated recommendations to help improve the agent when evaluation criteria aren't met.

Improve and retest

Agent development is an iterative process. Use evaluation results to refine the agent's:

• Instructions
• Tools
• Knowledge sources
• Output format

After making changes, run another test and evaluation to validate the improvements. Repeating this process helps improve agent quality and confidence before publishing or using the agent in a production workflow.

Known limitations

The evaluation experience currently has the following limitations:

• Evaluations are only available for new agents created in workflows.
• You can't select a custom model for evaluations.
• To run an evaluation, you must complete at least one test run and configure at least one test method.
• Evaluations run against the most recent test output. If you update the agent's instructions, tools, knowledge, or configuration, run a new test before reevaluating.
• You can generate up to five AI-generated test methods per agent node.
• You can run up to 20 evaluations per agent node per day.

Automation scenarios

An agent node is at its best as one step in a longer workflow. Earlier steps gather and normalize the inputs, the agent does the reasoning, and later steps act on the result across multiple systems.

Triage incoming support tickets

A workflow triggers when a new ticket is created in Dataverse. Earlier steps pull the ticket body, attachments, and the customer's recent case history. The agent node then reads everything, grounds itself in the product knowledge base, and returns a structured output with category, priority, suggested_owner, and draft_reply. Later steps branch on priority to page the on-call engineer for outages or assign the ticket and queue the draft reply for review.

Review expense reports against policy

A workflow triggers when an expense report is submitted. Earlier steps load the line items and convert non-USD amounts so the agent reasons over a single basis. The agent node grounds itself in the policy SharePoint site and returns a per-line compliant flag plus reason. Later steps either autoapprove and post the journal entry to the AP system or start an approvals action with the agent's reasoning attached and wait for a finance reviewer.

Prepare a meeting briefing

A workflow runs each morning, lists the day's meetings from Outlook, and loops over each one. For every meeting, an earlier step pulls account context from Dynamics 365. The agent node then uses Work IQ to scan recent mail and Teams threads with the attendees and returns talking points, open risks, and recommended questions. Later steps format that output into an HTML briefing emailed 30 minutes before the meeting and post it as an adaptive card on Teams.

Extract data from Documents

A workflow can use data from documents in multiple ways. Two common scenarios are Outlook email attachments and SharePoint files.

For email, the Office 365 Outlook When a new email arrives trigger starts the workflow when an email is received. The agent node can then use the trigger output to extract data from the email's attachments.

For SharePoint, you can retrieve files using a SharePoint "Get file content" node and pass the files to the agent node, which can extract data from documents stored in the SharePoint site. Later steps can use the extracted information to update records, populate systems, or generate insights.

Frequently asked questions

When should I use an inline agent and when should I use an existing agent?

Use an inline agent when the agent's job is specific to one workflow and you want everything, including instructions, tools, knowledge, and output, to travel with the workflow. Inline agents are faster to set up and easier to reason about because the configuration is right next to the steps that use it.

Use an existing agent when the same agent is shared across multiple workflows or surfaces, or when the agent is owned by a different team and you just want to call it.

Can the inline agent be reused outside this workflow?

No. An inline agent is scoped to its workflow. If you find yourself building the same inline agent in multiple workflows, promote it to a published agent and call that agent from each workflow instead.

Related content

• Edit and manage your workflow in the designer
• Workflows overview