AI Agents

Working with Relay from an agent

Learn what an agent can do in Relay and how its changes reach your workspaces.

Overview

A connected agent works with Relay through a set of MCP tools. It can read, edit, organize and send your requests, read responses and History, set up variables and auth, create drafts, import APIs, generate code and edit scripts. It can't open WebSocket connections or change what a Relay window shows. Scripts it writes wait for your approval. Relay doesn't ask before an external agent sends a request, so use your agent's own permission settings to control that.

To connect an agent first, see Connecting an AI agent to Relay.

Know what an agent can do

TaskTools
Find workspaces, environments, collections and requestslist_requests, get_active_workspace
Read a request, with its secrets hidden, and its last responseget_request
Change a request's URL, headers, body or settingsupdate_request
Send a request and read the responsesend_request
Read more of a long response, or an earlier oneget_response, list_history
Create folders and collections, and move, rename or delete requestscreate_folder, move_item, rename_item, delete_item
Read and change variables, with secret values hiddenlist_variables, set_variables
Read and set auth, using variables for credentialsget_auth, set_auth
Create a draft request, including a WebSocket requestadd_draft
Turn a curl command into a draftadd_draft_from_curl
Import an OpenAPI spec, a Postman collection or a Postman environmentimport_collection, import_openapi
Write code that sends a request, in any of Relay's code generatorslist_generators, generate_code
Create a code generator of your ownget_generator, test_generator, create_generator
Read and write pre-request and post-response scriptsget_scripts, set_scripts

You don't name the tools yourself. Describe what you want, and the agent picks them:

  • "Add a Relay draft for the endpoint I just wrote, with an example JSON body."
  • "Import our OpenAPI spec from https://api.example.com/openapi.yaml into my current Relay workspace."
  • "Turn this curl command into a Relay request."
  • "Generate Python code for the Create Order request in Relay."
  • "Add a test to the Create Order request that checks for a 201 status and saves the order ID to the environment."

Point the agent at a workspace

Each Relay window shows its own workspace, so an agent has no current workspace to assume. When Relay has more than one workspace, the agent names the one it wants for anything that adds to a workspace, such as an import. When you say "my current workspace", the agent uses the workspace of the Relay window you used last.

An import without a workspace creates a new workspace, stored in Relay. No window switches to it; choose it from the workspace menu when you want to see it.

Find the drafts an agent creates

Drafts an agent creates appear in the Drafts section of the sidebar, in every window. A draft the agent tied to a workspace uses that workspace's variables and auth. A draft without a workspace uses the variables, environment and auth of the window you view it in, and joins that window's workspace when you edit or send it.

The agent doesn't open or select anything in your windows. Select the draft in the sidebar to review and send it, and save it to a collection if you want to keep it. To learn more about drafts, see Creating and managing requests.

Review scripts before they run

A script an agent writes is saved in the request, folder or collection, but it doesn't run until you allow it. When you open its Scripts tab, Relay shows "This script changed outside Relay". Read the script, then click Allow. The same applies to scripts in collections an agent imports. For details, see Allowing scripts to run.

Understand what an agent can't change

An agent can't change a workspace that's read-only because files in its folder can't be read, such as during a Git merge, or a workspace Relay can't find. Its tools return an error that explains why until you fix the files or locate the workspace. Drafts can always be changed. To fix a workspace, see Resolving workspace file issues.

Changes an agent makes aren't part of any window's undo history. Delete a draft, collection or workspace you don't want the way you'd delete any other.

Choose whether generated code holds credentials

Code an agent generates keeps {{name}} tokens as written and shows placeholders, such as [redacted], instead of the credentials and cookies the request would send, the same way the agent's other tools hide secrets. To give agents code that runs as it is, choose Relay > Settings, click MCP, then turn on Reveal Credentials in Generated Code.

Important

With Reveal Credentials in Generated Code turned on, code an agent generates contains your real credentials, such as tokens and passwords from the request's auth. Review it before you commit or share it.

See Also