Quick start: Build and deploy an agent

Task 1a: Create the deployment space

Before you can deploy the model, you need to promote the agent to a new deployment space. Deployment spaces help you to organize supporting resources such as input data and environments. Follow these steps to create a deployment space:

1. From the Navigation Menu , choose Deployments.
2. Click New deployment space.
3. Provide the Space name; for example: Agent deployment space
4. Select your machine learning service from the list.
5. Click Create.
6. When the space is created, click View new space.
7. Click the Manage tab.
8. Next to the Space GUID, click the Copy to clipboard icon .
9. Save the value for the Space GUID in a text file to use later in the Python code.

Check your progress

The following image shows the deployment space.

Task 1b: Create an API key

You need to pass your credentials to the watsonx.ai API using an API key. If you don't have an API key, then follow these steps to create the API key:

1. From the Navigation menu , choose Administration > Access (IAM).

2. Click the API keys page.

3. Click Create.

   1. Type a name and description.

   2. Click Create.

   3. Copy the API key.

   4. Download the API key for future use.

4. Save the value for the API key in a text file to use later in the Python code.

Check your progress

The following image shows the API key was successfully created.

Task 1c: Obtain the watsonx.ai URL endpoint

You need the endpoint for your region to use the APIs to build and deploy your agent. Follow these steps to obtain this information:

1. Visit the Developer access page.
2. Next to the watsonx.ai URL, click the Copy icon .
3. Save the value for the watsonx.ai URL in a text file to use later in the Python code.

Check your progress

The following image shows the Developer access page.

Task 2a: Download the agent template

1. Install the IBM watsonx.ai CLI by running the following command:

   pip install -U ibm-watsonx-ai-cli
   

2. Download the agent template. For details about supported agent templates, see Official agent templates in the watsonx-developer-hub GitHub repository.

   The following command downloads the arXiv Research Agent template:

   watsonx-ai template new community/langgraph-arxiv-research
   

   When you run the command, a prompt appears where you can specify the target directory as the location to store the agent template or use the default directory name.

Task 2b: Install the agent template

1. Navigate to the directory that contains the agent template by running the following command:

   cd langgraph-arxiv-research/
   

2. Use one of the following package installers to set up the Poetry tool for Python package and dependency management:

   For pipx:

   a. Set up the environment by installing Poetry.

   pipx install --python 3.11 poetry
   

   For uv: a. Set up the environment.

   uv venv --python 3.11
   

   b. Install Poetry.

   uv pip install poetry 
   

   Important: You can use any other tool to run your Python code. Use the Python version that is available on your system to set up the environment and make sure to use Python version 3.11 or higher.

3. Use Poetry to install Python dependencies.

   poetry install 
   

4. Optional: Run the following commands to install the repository in a separate virtual environment:

   On a Unix-based operating system:

   source $(poetry -q env use 3.11 && poetry env info --path)/bin/activate # start the environment
   

   On a Windows operating system:

   source "$(poetry -q env use 3.12 && poetry env info --path)/Scripts/activate"
   

Check your progress

The following image shows the template installed successfully.

Task 2c: Set the enviroment variables

Before you can run the agent locally, you need to edit the configuration files to provide the credentials to use the watsonx.ai APIs. Follow these steps to add the working directory to the Python path and edit the configuration files:

1. Add the working directory to the PYTHONPATH by running the following command:

   export PYTHONPATH=$(pwd):${PYTHONPATH}
   

2. Make a copy of the template.env file and rename the configuration file to .env.

   cp template.env .env
   

   Open the .env file in a text editor and replace the values for WATSONX_APIKEY, WATSONX_URL, and WATSONX_SPACE_ID with the values that you stored in a text file in Task 1.

3. Make a copy of the config.toml.example file and rename the configuration file to config.toml.

   cp config.toml.example config.toml
   

   Open the config.toml file in a text editor and enter values for the following parameters in the [deployment.online.parameters] section:

   • url : Add the watsonx.ai URL based on your region.
   • model_id : Replace the default value with the ID of a foundation model that is available in your region.

Task 2d. Run the agent locally

You can run the agent locally and interact with the agent through a terminal-based chat application.

Use the following command to run the agent:

watsonx-ai template invoke "show me the latest arxiv papers on the model context protocol"

Check your progress

The following image shows the answers provided by the agent.

Task 3a. Deploy the agent

Deploy the agent as an AI service to IBM Cloud with the following command:

watsonx-ai service new

Check your progress

The following image shows that the agent deployed successfully.

Task 3b. Test the agent

Test the agent by sending inference requests to the deployed AI service with the following command:

watsonx-ai service invoke 'Hello, how can you help me?'

Check your progress

The following image shows the answers provided by the deployed agent.

Task 3c. Preview the agent in the dashboard

Once an agent is deployed to watsonx.ai, you can find the API endpoint to connect to the agent from a remote location or directly interact with the agent using the built-in chat interface. Follow these steps to use the agent through the chat interface in the watsonx user interface:

1. From the Navigation Menu , choose Deployments.

2. Open the deployment space that you created in Task 1.

3. Click the Deployments tab.

4. Open the deployment you created in Task 3a.

5. Notice the private and public API endpoint of the agent.

6. Click the Preview tab. If you don't see the Preview tab, then follow these steps to enable the tab:

   1. Click the View AI service info icon .
   2. For the Tags field, click the Edit icon .
   3. Type wx-agent.
   4. Click Save.

7. In the chat interface, you can ask the same questions as you did when running the agent locally, for example: show me a list of arxiv papers about deepseek.

   The answer includes a list of papers published on ArXiv that mention DeepSeek. You can also see what tools the agent called to retrieve this information.

Check your progress

The following image shows the answers provided by the deployed agent in the deployment space.