Agent Mode

Agent Mode is an AI assistant in a panel next to your requests. Ask it to write tests for a request, explain a response, document an endpoint or find out why a call fails, and it does the work: it reads the request, sends it, edits it and runs collections, using tools that act on your workspace. It uses your own key for Anthropic, OpenAI or Google Gemini, or a model running on your Mac, so there are no credits or limits.

Set up Agent Mode

1. In the API client, click Agent in the toolbar or press ⇧ ⌘ I. The panel opens on the right.
2. Pick a Provider: Anthropic, OpenAI, Google Gemini or OpenAI-compatible.
3. Optionally type a Model. Empty uses the provider’s default, shown in the field.
4. For OpenAI-compatible, enter the Base URL, for example http://localhost:11434/v1 for Ollama.
5. Paste your API key and click Save. Local servers usually don’t need one.

The settings appear by themselves until a key is saved (except for OpenAI-compatible). To change them later, click the gear button at the top of the panel.

123456

Agent Mode next to the request it's working on.

1. Provider
2. Model; empty uses the default
3. API key, saved in the Keychain Vault
4. Quick actions
5. Ask anything
6. Settings and New Chat

×

Where your key is kept

The key is saved in the Vault, which is the macOS Keychain, under a name for each provider:

Provider	Vault name
Anthropic	anthropic_api_key
OpenAI	openai_api_key
Google Gemini	gemini_api_key
OpenAI-compatible	openai_compatible_api_key

The key never goes into the workspace files. Requests go straight from your Mac to the provider, not through any Subcloak server. New AI requests use {{vault:anthropic_api_key}} as their API key, so a key saved here works there too.

Ask the agent

Open the request or collection you want help with, then either click a quick action or type in Ask the agent… and click the arrow button to send.

Quick action	What the agent does
Write tests for this request	Runs the request to see the real response, writes pm.test tests for the status, response time, the JSON body’s schema and important values, saves them, and runs it again to check they pass.
Explain this response	Explains the last response: what it means, anything unusual in the status, headers, errors or timing, and what to check next.
Document this request	Writes Markdown docs (purpose, parameters, body, example response) and saves them in the request’s Docs tab.
Debug the failing request	Runs the request, reads the status, body, test results and script errors, finds the cause and fixes the URL, headers, auth, body or variables.
Generate requests from this response	Creates follow-up requests in the same collection for related endpoints it can infer, such as fetching one item by ID.

The quick actions appear when the chat is empty. You can ask anything else too, for example “Add a test that every pet has a name” or “Create a POST request that creates an order”.

While the agent works, the panel shows what it’s doing, such as “Running run_request…”, and each tool it used appears under its reply. Stop cancels the current task. New Chat clears the conversation. The conversation isn’t saved; it’s gone when you quit.

The agent knows which tab is selected: a saved request, an unsaved request or a collection. Name a different request or collection in your message to work on that instead.

What the agent can do

The agent acts through these tools. It can’t do anything else in the app.

Tool	What it does
list_collections	Lists collections with their folders, requests and variable names, and the environments.
get_request	Reads a request’s full definition (method, URL, headers, body, auth type, scripts, docs) and its last response and test results.
run_request	Sends a saved request with its scripts and the active environment, and reads the status, headers, body, tests and console output.
update_request	Changes a request’s method, URL, headers, body, post-response script, pre-request script, docs or name. Only the fields it passes change.
create_request	Creates a request in a collection, creating the collection if it doesn’t exist.
run_collection	Runs a whole collection with its tests and reads the results.
set_variable	Sets a variable in the active environment, or in Globals when no environment is active.

The agent takes up to 16 steps per message. Requests it runs are sent like yours: through Cloak Proxy if the request’s settings say so, and into History.

The agent changes your workspace

Edits the agent makes are saved to your workspace right away, and requests it runs really go to the server, including POST and DELETE requests. Point it at test environments, not production. If the workspace is in Git, review its changes in the Git view before you commit, and use Discard Changes to undo one.

What the model sees

To do its work, the agent sends the model your requests and their responses: URLs, headers, bodies (the first 6,000 characters of each response), scripts and docs. With a cloud provider, that data leaves your Mac and is handled under that provider’s terms. Header values can include tokens. For sensitive APIs, use a local model through OpenAI-compatible (Ollama or LM Studio), or keep credentials in the Vault so requests show {{vault:name}} instead of the secret.

Use a local model

1. Install and start a local server, such as Ollama or LM Studio, and download a model that supports tool use.
2. In the Agent panel’s settings, choose OpenAI-compatible.
3. Set Base URL to the server’s OpenAI-compatible endpoint, such as http://localhost:11434/v1 for Ollama.
4. Type the model’s name in Model.
5. Leave API key empty unless your server needs one.

Smaller models may not handle tools as reliably as large hosted ones. If the agent stops early or calls the wrong tool, try a larger model.

Other ways to work with AI

• AI requests send prompts to a model as saved requests, and can give the model tools from your MCP servers.
• The MCP server (cloakctl mcp) gives Claude Code, Cursor and other MCP clients the same workspace access and more, including captured traffic. See Debug with Claude.

Related

Scripts and testsThe pm API the agent writes tests with.

AI requestsPrompts, models and MCP tools as requests.

MCP serverUse Cloak Proxy from Claude Code and Cursor.

Variables and environmentsThe Vault that holds your API keys.