Best practices

Follow these best practices to use the API Agent extension in Visual Studio Code or IBM API Studio, effectively. Ensure that the extension window is full height and at least one third of the Visual Studio Code window for optimal performance.

Guidelines for using prompts

To achieve accurate and efficient results, use the following guidelines when you enter the prompt:
  1. Avoid the words or tone that convey sarcasm or humor, as they can be misinterpreted.
  2. Use active voice, correct grammar, spelling, and keep your request clear and specific.
  3. Provide clear context and relevant keywords, and avoid vague or domain-specific terms. For example, generate test or build API.
  4. If the system is unable to understand your request, it offers suggestions for the requests.
  5. Use the following sample prompts to get accurate answers:
    1. For documentation search, enter the prompt: Search the documentation for.
    2. For critical details, Cross-check with official IBM documentation before implementing.
    3. Include version number in your query for specific product version.
    4. If answers are different cross-check with official documents.

Prerequisites

The API Agent plug-in can be used to complete tasks that are related to API Connect.

  • Ensure that you are logged in to API Agent. For login and operation instructions, see Getting started.
  • You must have valid permissions to use the API Agent. For more information, see API Agent user roles.
  • Ensure that you have the same permissions through the API Connect’s API Manager interface. Even if you have permission to use the API Agent plug-in, actions fail if you do not have the necessary permissions to complete the same tasks through the API Manager UI.

Understanding prompts in documentation

Replace placeholders in commands
If a command contains a placeholder such as [apiName], replace it with your API name.
  • Command Run test cases for [apiName]:[version]
  • Replacement Run test cases for bookshop-api-3:1.0
Populate the placeholder such as [@file]
The document might have the following prompt: remediate api [@file] using spectral-owasp ruleset. Replace it with remediate api @bookstore.yaml using spectral-owasp ruleset.

To replace [@file], you need to trigger the @ symbol to access the files in your Visual Studio Code workspace. Then, select the wanted file to upload to the agent.

For more information about common issues, see Troubleshooting.

The following sections provide steps to start a new session with the API Agent, including clearing temporary data, refreshing the system, and logging out of the current session.

Sequential prompts

Use API Agent to chain multiple tools together in a single prompt and then run one after another. The following are examples of sequential prompts:
Create and run test cases
create test cases for the petstore api and run the test cases

List published APIs or products 
list apis, products, published apis and published products
Or
list published apis

Create an API and generate FastAPI server code
create api from file @openapi.yaml and generate fastapi server code from the same api file
Or
create api using @file_name
Review security of an API 
review security of api API_NAME:VERSION
Or 
validate api API_NAME:VERSION