Flows referenceBlocksAI

The AI Agent block

View as Markdown

The AI Agent block is an AI assistant that can automate tasks in Postman Flows. There are two AI Agent blocks: AI Agent Legacy and AI Agent with MCP Server support. The AI Agent Legacy block responds to natural language prompts by analyzing data, generating content, making decisions, and calling other flows. The AI Agent with MCP Server support block does the same, but instead of calling other flows, it invokes tools exposed by MCP Servers.

The AI Agent blocks use one of several AI models to interpret prompts and act on available context. You can pass data to the block as variables in the Context section, and each variable’s label helps the block understand the variable’s purpose. The AI Agent Legacy block can also use other flows as tools to complete its tasks. The AI Agent with MCP Server support block can use MCP Servers to build agents that can complete autonomous tasks.

For example, you could give the AI Agent Legacy block a list of API endpoints as a variable named endpoints_list. Then, you could select a flow from the Tools section that sends a GET request to a provided endpoint. When you prompt the AI Agent Legacy block to “Get the content headers for each endpoint in endpoints_list,” it automatically runs the tool for each one and outputs the results. Or you could give the AI Agent with MCP Server support block a Slack channel ID and add a Slack MCP Server to create an agent that sends updates to the Slack channel with the ID you provided.

Input

Context - Variables you can reference in your prompt using plain text. The variable’s name is called a label here because the AI Agent block interprets context about the variable’s value from the its label. For example, an endpoints label provides more context than a label like variable-1. Click Add icon Add data blocks to add more variables. You can add variables to the Context section using any of the following data blocks:

Outputs

Result - Sends the result of the AI Agent block’s task.

Evals - Sends structured eval results when you turn on quality evals or add custom evals. See Evals.

Setup

Model - Select the AI model from the dropdown list that best suits your task. Different models consume different amounts of credits. See Manage your team’s Postman Flows credit usage for details about how the AI Agent block consumes credits.

Prompt - The system prompt for the AI agent. A system prompt is static and persists for the duration of the task. Enter a prompt in natural language that describes what you want your agent to do. You can reference variables in the prompt by including the variables’ labels as plain text. If you added tools to the block, the AI Agent block automatically uses them if needed to act on the prompt.

Tools - Tools are flows your AI Agent Legacy block can run automatically. The AI Agent Legacy block tries to generate any input data it needs from its own knowledge or from variables you’ve provided. To use a flow as a tool, the flow must have at least one snapshot.

To add a tool, do the following:

  1. Click the AI Agent Legacy block.

  2. Click Add a tool.

  3. Select a tool from the dropdown list.

To select a different snapshot of a tool, do the following:

  1. Hover over the tool.

  2. Click Versions icon.

  3. Select a snapshot from the dropdown list.

When a tool uses inputs, the AI Agent Legacy block automatically populates those inputs with AI-generated data. You can also assign static values to the inputs with a configuration.

Postman Flows doesn’t pass static configuration data to the LLM to preserve the security of any secrets.

To select a configuration for a tool, do the following:

  1. Hover over a tool.

  2. Click Setting icon Edit Tool.

  3. Next to the input, click Magic icon AI-generated.

  4. Select a configuration from the dropdown list or click Open web icon Add configuration to create a new one.

MCP Servers - MCP Servers expose specific functionalities that the AI Agent with MCP Server support block can use to create agents to automate tasks. There are two types of MCP Servers available: flows that have been deployed as MCP Servers, and external MCP Servers.

Adding external MCP Servers consumes credits for each unique external MCP Server that your AI Agent calls. If you call the same external MCP Server multiple times, it only consumes credits once for that unique server. Adding Postman Flows deployed as MCP Servers does not consume any credits. To learn more see, Manage your team’s Postman Flows credit usage.

To add an MCP Server, do the following:

  1. Click the AI Agent with MCP Server support block.

  2. Click Add MCP flow if you have any flows in your workspace that have been deployed as MCP Servers. A list of available flows deployed as MCP Servers appears in the dropdown.

  3. Click Add server to add an external MCP Server and enter a name and URL for your MCP Server.

    • (Optional) Enter a bearer token if your MCP Server requires one. When you enter a bearer token, Postman Flows saves it as a secret value in a new configuration. The next time you add an MCP Server, you can choose to reuse that secret bearer token or create a new one.

  4. Click Add to add the MCP Server.

Additional Settings - Appears when you click the block, and enables you to select an AI model or enforce an output schema that you can parse later in the flow.

To enforce an output schema, do the following:

  1. Click the AI Agent block, then click Setting icon Additional Settings.

  2. Click JSON icon Enforce output schema > JSON icon Schema.

  3. Click Generate from example and paste valid JSON data into the text box, then click Generate schema. Alternatively, click Define custom schema to manually enter a JSON schema.

Evals - Click Add icon Evals on the block to grade its output with evals, which use an AI model as a judge. Turn on any of the built-in evals under Quality presets (Friendliness, Safety, Non-toxicity, Correctness, Relevance), or add your own under Custom. See Evals for details, or Add evals to a flow for step-by-step instructions.

Evals

Evals are opt-in and don’t run unless you configure them. Each enabled eval is a separate judge call that consumes Flows credits.

  • Quality presets grade the output for Friendliness, Safety, Non-toxicity, Correctness, and Relevance. Turn on each eval you want to run.
  • Custom evals grade the output against a criterion you write in natural language. Give each custom eval a name and a criterion of up to 4,000 characters. You can add up to 50 custom evals, and the five quality presets don’t count toward this limit.

The passing threshold is fixed at 80 on a 0–100 scale, and the judge model is fixed at gpt-4o-mini-2024-07-18. The block automatically gives the judge the agent’s prompt and inputs as context, which can give criteria such as Correctness and Relevance enough grounding to produce a score. This also means a check here can score differently from a similar pm.eval check on the Evaluate block, which receives only the context you pass to it and defaults to a different judge model.

Before a run, the block shows No eval results yet. Run the flow to grade this response. After a run, a preview shows a summary, such as Passed 3/4, with a row for each eval and its score. A failed eval was graded but didn’t meet its passing threshold. A skipped eval means the judge lacked the information to grade the output, and it’s left out of the summary counts.

Evals run when the flow runs, on the canvas, in local mode, and in deployed and scheduled flows. They aren’t supported by the Postman CLI. Eval failures don’t fail the flow, and the run still completes if grading can’t complete. When grading fails, the block shows Grading failed, and the All evals tab in the run log marks the block as Grading failed with no evals graded. Results also appear through the Evals output port and in the All evals tab of the run log. For details, see Evaluate AI output with evals, Add evals to a flow, and Manage your team’s Postman Flows credit usage.