Build and deploy Agents to watsonx.ai from your IDE

An artificial intelligence (AI) agent refers to a system or program that is capable of autonomously performing tasks on behalf of a user or another system by designing its workflow and utilizing available tools. These agents can be deployed in various applications to solve complex tasks in various enterprise contexts from software design and IT automation to code-generation tools and conversational assistants.

They use the advanced natural language processing techniques of large language models (LLMs) to comprehend and respond to user inputs step-by-step and determine when to call on external tools.

Building AI agents just got easier! You can now build and deploy agents on watsonx.ai directly from your integrated development environment (IDE) or command line using the new agent templates. The first available template helps you to build a ReAct research agent powered by LangGraph, making getting started with creating agents simpler for developers. The agent template can be a basis for building customer support bots, automation assistants or research agents, this template provides a solid foundation to accelerate development.

In this guide, we’ll walk through how to get started with the new agent template, from installation to deployment. At the end of this tutorial, you’ll have a research agent that runs in the cloud, and can be accessed from the watsonx.ai dashboard or via its endpoint.

To build and deploy your first agent using the agent templates, sign up for a free watsonx.ai trial then follow the instructions below.

The agent in this template has access to two tools: web search via DuckDuckGo and a tool to retrieve the contents of papers published on ArXiv. By default, it will use the model Mistral Large but you can connect it to any model that supports tool calling and that’s available on your watsonx.ai environment.

You can use this agent to, for example, search for papers about DeepSeek on ArXiv. And ask it to summarize any of the papers that it found.

Let’s get started by setting up the agent template locally, before deploying it to watsonx.ai and access it from the cloud.

You would need to have Python installed on your machine, preferably using a Python environment manager like pipx or uv.

1. From your IDE or command line, you need to clone the repository with the agent templates. You can do this by running the following commands:

By using ‘sparse’ while cloning the repository we limit the number of tracked files to a subset of only the required files.

2. Once the files have been copied to your machine, you can install the required dependencies.

• Using ‘pipx’:

• Using ‘uv’:

The templates uses Poetry for dependency management, but you can use other Python-based dependency managers if you’d like. Ensure you use Python v10 to v13.

3. Set the environment variables needed to connect to models in watsonx.ai and the deployment space for the agent.

Open the file ‘config.toml’ and add the following values:

• ‘watsonx_apikey’: IBM Cloud API Key
• ‘watsonx_url’: API URL, e.g., https://us-south.ml.cloud.ibm.com
• ‘space_id’: ID of the deployment space with an active watsonx.ai runtime

To find your values, visit the Developer Access page in the watsonx.ai dashboard.

4. You can now run the agent from the template locally by running:

This will start a chat application directly in your terminal. Choose one of the pre-defined questions or ask the model your own question. Please bear in mind that the research paper should be available on arXiv if you want the agent to be able to summarize it.

You can modify the agent by editing the files ‘agent.py’ or ‘tools.py’, for example to give the agent different tools or change the model parameters. All the tools that are supported by the LangGraph framework or community can be used, or you can write your own Python function that the agent can execute.

The next step is to deploy this agent to the cloud, so it can be used from a remote location via its API endpoint.

Now that you’ve tried out the agent locally, it can be deployed to the cloud. For this, you’d need to set up a deployment space in watsonx.ai with an active watsonx.ai runtime linked to it. The ID of this space should be added to the ‘config.toml’ file as mentioned in Step 3 of the previous section.

To deploy the agent run the following command:

Deploying the agent might take a few moments, and once succeeded the ‘deployment_id’ will be printed in your terminal:

You would need this ID to access the agent via its API endpoint, this ID can also be found in your watsonx.ai dashboard under “Deployments” and opening the space you just deployed the agent to.

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. To use the agent via the chat interface follow these steps:

1. Find your newly deployed agent in the watsonx.ai dashboard under “Deployments” where you should open the space you just deployed the agent to.

2. By clicking on the space (in this case “agent test”) you can find the list of deployments, after running the script from the previous section you should see a new deployment in this list.

Make sure to check the deployment has the tag ‘wx-agent’ as this is needed to interact with it via the “Preview” tab.

3. After clicking on the latest deployment, you can see the private and public API endpoint of the agent, you can also see a "Preview” tab which you’ll need to open to test the agent in the chat interface.

4. In the chat interface you can ask the same questions as you did when running the agent locally, for example": “show me a list or arxiv papers about deepseek”. This should return a list of papers published on ArXiv that mention DeepSeek. You can also see what tools the agent called to retrieve this information.

Of course, you can use the chat to ask follow-up questions to get more information about a certain paper or ask it to find different ones.

5. You can also access the generated endpoint of your deployed agent directly from a remote source, and integrate the agent into third-party applications or watsonx Orchestrate.

Ready to start building agents? Sign up for free trial of watsonx.ai.

Want to develop agents without code?  Learn more about the all new Agent Lab in watsonx.ai.

Have a question? Explore the Developer Hub.