Working with AI Agents: Best Practices, Privacy, and Troubleshooting

Use Chat mode to explore ideas, ask questions, and refine responses through an interactive conversation. Use Task mode to run a specific operation and save the results to History for later review or auditing.

As a general rule, if you expect to run the same operation repeatedly, use Task mode.

Agents can act across your entire organization or on a single resource, so clear, specific instructions help improve accuracy and reduce processing time. Be as specific as possible when giving instructions. For example, instead of"Fix the issues", use "Fix all standardization issues in the Payments API v3.0." Providing more context helps the agent produce more accurate results.

The Instructions field is optional, but it can improve results by narrowing the scope, defining constraints, or supplying context that the agent would not otherwise have. Examples of useful instructions include:

Short, specific instructions generally produce more consistent and predictable results than lengthy or ambiguous requests.

To work on the API you currently have open in the editor, click the Governance Agent widget that appears below the code editor instead of opening the agent from the toolbar. This launches the agent with the current API already in context, so you can enter prompts about it without specifying its name.

On any completed task, click Discuss results to open the chat with the task output already in context. From there, you can ask follow-up questions, request modifications, or explore the results further without running the task again.

Swagger Studio saves every task run in the History tab, including the tools the agent called and their inputs and outputs. Use this record to audit activity, debug unexpected results, or share details with a colleague.

Click Reset at the top of the agent widget to clear the active conversation and its context. This does not affect your task history.

Model Context Protocol (MCP) is an open standard that allows agents to connect to external tools and systems. Without an MCP server, an agent can only respond based on its training knowledge. Using an MCP server, it can perform actions such as reading live API definitions from Swagger Studio, checking governance rules, or saving new versions. The built-in SmartBear MCP server handles this automatically for both the Governance Agent and the Portal Agent.

Some MCP servers require you to grant access before an agent can use them. This happens the first time you use an agent that connects to such a server. Once you authorize, the connection is remembered for future sessions and you will not be prompted again unless your session expires or you revoke access.

You can modify the MCP server connection from the agent settings. Click Work with Agents on the toolbar, open the settings icon, and navigate to the Tools tab. Click Disconnect and complete the updated authorization flow. To fully revoke access, contact your Swagger Studio administrator.

Agents operate within your organization's boundaries. Through the built-in SmartBear MCP server, they can access your organization's API definitions, governance rules and developer portal products. Agents cannot access data belonging to other organizations.

An agent always asks for your confirmation before applying any changes. It saves governance fixes as new API versions and never overwrites the original. It saves portal documentation as a draft that you must publish manually before it becomes visible. If you are unsure about a proposed action, decline and ask the agent to explain its reasoning first.

Large language models (LLMs) generate all agent responses. Swagger Studio sends your messages, along with any relevant context such as API definitions referenced in the conversation, to the configured LLM provider for processing. Your organization's configuration determines which provider Swagger Studio uses. Any data sent to the provider is subject to that provider's privacy and data handling policies.

Only you can access your task history and conversation. Other members of your organization cannot view them.

Check your internet connection and try refreshing the page. If the agent relies on an MCP server to read your APIs, that server may be temporarily unavailable - wait a moment and try again. If the issue persists, contact your Swagger Studio administrator.

Try rephrasing your request with more specific instructions and a clearer scope. Review the task in Task History to see which tools the agent used, as this can help identify the source of the issue. If the result is consistently incorrect, contact your Swagger Studio administrator to check the agent's configuration.

Ensure that all required fields for the selected skill are populated.

Expand the task in the History tab to read the full error message. Verify that the API name and any other arguments are correct and exist in Swagger Studio, then try again with a more specific scope. If the same task fails repeatedly, contact your Swagger Studio administrator - there may be an issue with the agent's tool configuration.

Make sure the API name and version match exactly what Swagger Studio shows - API names are case-sensitive. If you are unsure of the exact name, ask the agent in Chat mode: "List all APIs in my organization."

Some tasks, such as scanning a large number of APIs, may take several minutes to complete. If a task remains in progress for more than 10 minutes, refresh the page and check its status again.

Complete the OAuth flow in the pop-up window that opens. If the prompt reappears after authorizing, your token may have expired - authorize again to refresh it. If the issue continues, contact your Swagger Studio administrator to verify the MCP server's OAuth configuration.

Reopen the widget and start a new chat or task with the same agent. The authorization prompt will appear again.

The agent always saves governance fixes as new API versions, so Swagger Studio preserves the original. To revert, open the API in Swagger Studio, navigate to version history, and restore the previous version.

Make sure you opened the agent using the widget that appears below the code editor, not from the toolbar. Opening from the toolbar does not automatically load the current API as context - in that case, specify the API name explicitly in your message.

The agent saves the generated portal documentation as a draft. To make it available in the developer portal, publish the draft manually. If you cannot find the documentation, check the portal's draft content.

The Portal Agent generates documentation based on the API definition. If the output is incomplete or inaccurate, review the definition for missing fields, unclear descriptions, or structural issues, then run the skill again.