Set up IBM watsonx (Optional)

If you are working as part of a team, please plan to collaborate using one team member’s IBM Cloud account. Adding or removing team members is not supported on the hackathon-provisioned IBM Cloud accounts.

The IBM Cloud account provided for this hackathon is pre-configured with only the services needed to complete the event challenges. To help maintain a consistent and secure environment for all participants, you will not be able to add new services or modify access permissions for existing services.

If you encounter an access or permission issue when trying to use a service or view items in the IBM Cloud catalog, it likely means that the service is not required or is not available for this hackathon. Only the services needed for the event have been enabled in your account.

The following optional IBM Cloud services are provided for your hackathon solution building:

• Speech-to-Text
• Text-to-Speech
• Cloudant

Hackathon participants may use IBM Cloud credentials to build their solutions that leverage IBM technologies on IBM Cloud. During development, testing, collaboration, or while submitting their final project in a public repository, participants may unintentionally expose these credentials on publicly accessible platforms.

Exposing IBM Cloud API keys or any cloud credentials can lead to unauthorized access, misuse of resources, and account suspension. If any IBM Cloud credential associated with your hackathon account is detected in a public repository or publicly accessible platform:

• The credential will be deactivated immediately.
• Your hackathon cloud account access will be suspended until you:

1. Remove the exposed credential from all public sources. If you are using GitHub, you can refer to Removing sensitive data from a repository.
2. Rotate and replace the exposed credential.
3. After completing these steps, confirm remediation with the hackathon support team and request access to your hackathon cloud account.

Please follow the Preventing exposure of IBM Cloud credentials in public repositories and platforms guide for best practices to avoid disruptions to your project and ensure the security of your IBM Cloud resources.

For this hackathon, $80 credits will be automatically applied to your provisioned IBM Cloud account. These credits should be sufficient for designing and creating compelling submissions using the services available on your account.

You will receive periodic email notifications about your credit consumption at the following usage levels: 25%, 50%, and 80%. Once you reach 100% usage, your account will be suspended. You can appeal the suspension by completing the form shared in the account suspension notification email.

Please note that these email notifications are sent once per hour, so there is a possibility that you may exhaust all your credits before receiving an alert.

We recommend planning your usage carefully and backing up your work regularly to avoid disruptions.

Follow the steps below to request your cloud account:

1. Access the hackathon’s IBM Cloud account request URL in your browser: https://www.ibm.com/account/reg/us-en/signup?formid=urx-54436.
2. Create an IBMid if you have not already created one using the same email you used to register for the hackathon by completing the account information. Then click the Continue button.

If you already have an IBMid that uses the same email you used to register for the hackathon, proceed to log in, complete the authentication process and skip to step 6.

3. Enter the optional additional information, read and accept the privacy policy and click the Continue button.

4. Enter a strong password for your IBMid and click Continue button.

5. Verify your email by entering the 7-digit code sent to your email and select the Continue button.

6. Once IBMid authentication is complete, your cloud account request will be submitted, and you will see an Account requested confirmation message. You will then receive an email invitation to join your cloud account. Follow the Accessing your hackathon IBM Cloud account instructions to access your account.

Once you have been provisioned an IBM Cloud account, participants will receive an email invitation to join the hackathon-provisioned cloud account. Follow the steps below to access your cloud account:

1. Check the email inbox you used to register for the hackathon and open the email you received from the IBM Cloud team about joining your cloud account. Please check your junk/spam folders if you are not able to find the email in your inbox. You can also quickly search for “IBM Cloud” to locate the email.
2. Click the Join Now button seen in that email. A new browser tab will open with the cloud account sign up page.

3. Review your account and personal information. Read and accept the Account notice and click the Join Account button.

4. Complete the authentication process by clicking the Continue button.

5. After you authenticate successfully, you will be taken to the IBM Cloud dashboard.

6. If you have an existing personal IBM Cloud account for the same email/IBMid, sometimes you will be directed to your personal account. In this case, please switch your account to the xxxxxxx - watsonx account. Select your account drop-down at top-right of the dashboard and select watsonx account. Refer to the below image on switching accounts in your cloud dashboard.

To begin building your solution, explore the capabilities and resources for each IBM watsonx product enabled for this hackathon.

1. IBM watsonx Orchestrate (Optional)

IBM watsonx Orchestrate is an intuitive, AI-powered platform that you can use to create, configure, and deploy intelligent agents that can automate business tasks. Whether you're automating repetitive workflows or building complex multi-agent systems, the platform is designed to support users of all skill levels.

2. IBM watsonx.ai (Optional)

A powerful AI studio that enables you to experiment with foundation models like IBM Granite through the Prompt Lab. It can be used to enhance your agents with natural language understanding, intelligent decision-making, and dynamic response generation—serving as an inference engine to make your AI agents smarter and more interactive.

After successfully joining the IBM Cloud account, you can access watsonx Orchestrate to begin working on the platform and building your solution.

With watsonx Orchestrate, you can:

• Build and deploy agents
• Automate tasks such as scheduling, data entry, and approvals
• Start small and scale up with advanced tools and integrations
• Explore the clean, guided UI that simplifies agent creation and management.

Explore a few demos on how to use watsonx Orchestrate.

These watsonx Orchestrate features/capabilities are out of scope for this hackathon:

• AgentOps (Preview)

1. In your IBM Cloud account dashboard, select the Navigation menu on the top left of the dashboard and select the Resource list option.

2. Expand the AI / Machine Learning section and select watsonx-Hackathon Orchestrate service.

3. You will be navigated to watsonx-Hackathon Orchestrate service instance dashboard. Select the Launch watsonx Orchestrate button.

4. You will be navigated to the watsonx Orchestrate platform with a welcome message and a new chat window.

Designing is the first step in building AI agents in IBM watsonx Orchestrate. In this phase, you explore available agents and tools, understand what you can reuse, and prepare to create your own agent when needed.

The Discover page is your catalog for finding and evaluating prebuilt agents, MCP servers, tools, and apps that you can use to automate work in IBM watsonx Orchestrate. From here, you can search, filter, and browse available assets, then use the selections directly in Orchestrate Chat to complete tasks. Learn more about discovering the catalog.

Developing intelligent, scalable, and reliable agents in watsonx Orchestrate requires a strategic, multi-phase approach. It goes beyond writing prompts or connecting APIs. Successful agents need thoughtful planning, structured development, testing, and ongoing governance. Learn more about preparing to build AI agents.

Building is the core stage in the Agent Development Life Cycle (ADLC) where you create agents, tools, and assistants by defining their logic, behaviors, and interactions. In this phase, you convert design intent into concrete capabilities that support your intended use cases.

In IBM watsonx Orchestrate, building involves creating the components that enable AI-powered automation and assistance.

By building agents, you can:

• Build agents that reason, decide, and act autonomously
• Create tools that extend agent capabilities
• Design assistants with conversational interfaces
• Configure knowledge sources and integrations

Build your first working agent in watsonx Orchestrate by following a guided path that covers creating, configuring, testing, and publishing an agent. Follow the essential steps to build your first working agent.

Creating and customizing an AI agent involves defining its purpose and personality through thoughtful descriptions and instructions. The description defines the agent's purpose and is used by orchestration systems to route requests to the right agent. The instructions define the agent's personality and tone, shaping how it responds and engages with users. You can also select an AI model and configure settings such as welcome messages, starter prompts, and voice interactions to create an effective user experience. Learn how to create an agent with AI or from scratch or from a template.

Agent orchestration enables you to build scalable, multi‑agent systems where a primary agent delegates work to one or more collaborator agents, each focused on a specific domain to complete tasks. Instead of building a single agent that tries to handle every step, you create a system of specialized agents that work together through structured delegation. Learn more about orchestrating agents.

You can build powerful, customizable agents using the IBM watsonx Orchestrate Agent Development Kit (ADK). The ADK empowers developers to build, test, and deploy agents tailored to specific business needs, all within the watsonx Orchestrate platform. It supports modular design, multi-agent orchestration, and integration with external tools and frameworks. Learn more on how to use the ADK.

In watsonx Orchestrate, you build the assistant by using Assistant builder. Assistant builder is a chat interface builder that helps to deploy an engaging and embedded chatbot experience. Assistant builder integrates the power of large language models (LLMs) and conversational capabilities of watsonx Assistant to enable responsive and interactive conversation between the users and watsonx Orchestrate.

To learn more, see Building assistants in AI Assistant builder.

Set up your agent to respond accurately, use the right tools, and access the knowledge it needs. Configuration determines how your agent behaves, what information it can access, and how it interacts with users. A well-configured agent delivers accurate responses, performs appropriate actions, and provides a consistent experience. Learn more about configuring agents.

Tools act as interfaces to external capabilities, enabling agents to interact with systems, retrieve data, run calculations, or trigger workflows that go beyond their built-in reasoning. You can build new tools and edit existing tools for your agents to use.

Following are the different ways to add a tool:

• Agentic workflows
• Open API tools
• MCP servers
• Customizing input-output schemas of prebuilt tools

Test and debug your agent to validate its behavior, identify issues, and improve performance before deployment. Testing and debugging help you verify that your agent responds as expected, uses the appropriate tools, and completes user tasks successfully. Use debugging to inspect how your agent processes individual requests. Use evaluations to measure performance across realistic user scenarios and identify opportunities for improvement. Learn more about testing agents.

Deploy your Watson Orchestrate agents to production and make them available to users. Deployment is the process of making your agent available to users in a production environment. A successful deployment ensures your agent is accessible, performs reliably, and delivers value to your organization. Learn more about deploying agents.

The Orchestrate Chat page is your main workspace for interacting with AI agents, running tasks, and managing conversations. From here, you can start new chats, explore what each agent can do, and complete actions quickly - all with a simple, intuitive interface. Learn more about using watsonx Orchestrate chat.

Operating is where you manage, monitor, and optimize AI agents in IBM watsonx Orchestrate to ensure they run reliably, perform effectively, and deliver expected outcomes. In watsonx Orchestrate, operating focuses on keeping your agents running smoothly and efficiently. Learn more about operating with agents.

IBM watsonx Orchestrate provides a set of APIs to boost your experience using the features from the product.

• Getting started with the API

Begin using the API with practical, step-by-step guidance.

• API reference

Get the methods that you can use to call custom projects, or other resources from the AI chat.

Try the quick start hands-on exercises for sample use cases to get started with using watsonx Orchestrate:

Important notes:

• You must use the hackathon-provisioned IBM Cloud account to access and use watsonx Orchestrate platform to try the below sample exercises.

watsonx Orchestrate SaaS sample exercises:

• Develop agents with no code using watsonx Orchestrate

A hands-on guide for developing a multi-agent system in watsonx Orchestrate with no code that can communicate with the agents on various channels.

• Creating intelligent, reusable agentic workflows on watsonx Orchestrate with no code

A hands-on guide for creating AI‑driven, human‑in‑the‑loop workflows without writing code.

• Build context-aware AI agents with watsonx Orchestrate and Astra DB

AI agents are only as effective as their data, making precise retrieval essential for reliable results.

• AgentOps in watsonx Orchestrate: Observability for Agents with Langfuse and IBM Telemetry

A developer’s guide for instrumenting and observing Agents with Langfuse and IBM Telemetry in watsonx Orchestrate.

• Building and deploying prebuilt domain agents in watsonx Orchestrate

Explore how to work with the prebuilt domain agents and integrate them into existing workflows.

• Build a scheduled agentic workflow for daily notifications

A practical example of building, importing, and scheduling an agentic workflow that automatically sends daily email notifications using watsonx Orchestrate.

• Multi-agent orchestration with watsonx Orchestrate

A hands-on journey to design, extend, and integrate AI agents by using Langflow, IBM Granite models, Astra DB, the AI Gateway, and a custom user interface on watsonx Orchestrate.

watsonx Orchestrate Agent Development Kit (ADK) sample exercises:

• Getting Started with watsonx Orchestrate Agent Development Kit

IBM watsonx Orchestrate includes the Agent Development Kit (ADK) which is a set of developer-focused tools for building, testing, and managing agents. With the ADK, developers get the freedom and control to design powerful agents using a lightweight framework and a simple CLI. You can define agents in clear YAML or JSON files, create custom Python tools, and manage the entire agent lifecycle with just a few commands.

• Build memory-enabled AI agents in watsonx Orchestrate

Use watsonx Orchestrate and the Agentic ADK to build agents that store user preferences and deliver personalized recommendations across conversations

• Build an AI agent with Langflow, Granite 4.0 models, and watsonx Orchestrate

A hands-on guide for creating Langflow tools, consuming them with watsonx Orchestrate Agent Development Kit, and using IBM Granite 4.0 Micro model for inference.

• Connecting to MCP tools with watsonx Orchestrate

A hands-on guide for creating MCP tools and consuming them with watsonx Orchestrate Agent Development Kit.

• Extend Your AI Agents with External LLMs Using watsonx Orchestrate and AI Gateway

A hands-on guide to bring your own model (BYOM) into watsonx Orchestrate using AI Gateway.

• Create consistent evaluation workflows for AI agents

A hands-on guide to setup and use a structured evaluation strategy to test, benchmark, and improve AI agent performance.

watsonx Orchestrate and IBM Bob sample exercises:

• Build agentic workflows with watsonx Orchestrate and IBM Bob

A hands-on guide to automate invoice processing with AI-powered workflows using IBM Bob to generate code, tools, and configuration for watsonx Orchestrate.

• Using IBM Bob to build watsonx Orchestrate agents and MCP tools

A hands-on guide for automating the full process of building and deploying an agentic workflow using IBM Bob.

• Turn BPMN diagrams into production‑ready agents with Bob skills and watsonx Orchestrate

A hands-on guide for using Bob skills to transform BPMN process models into SOP‑driven, fully tested, and deployable watsonx Orchestrate agents with best‑practice workflows, tools, and automation patterns.

After successfully joining the IBM Cloud account, you can access watsonx.ai to begin working on the platform and building your solution.

For this hackathon, $80 credits will be automatically applied for the IBM services provisioned on the cloud account. This should be sufficient for designing and creating compelling submissions.

You will receive periodic email notifications about your credit consumption at the following usage levels: 25%, 50%, and 80%. Once you reach 100% usage, your account will be suspended. You can appeal the suspension by completing the form shared in the account suspension notification email.

Please note that these email notifications are sent once per hour, so there is a possibility that you may exhaust all your credits before receiving an alert.

IBM watsonx.ai service consumes the credits when used. Please plan to use it efficiently and back up your work accordingly. Refer tips to work efficiently on watsonx.ai platform (Tokens and CUH explained) and saving your work.

Important:

• Foundation model inferencing consumes tokens, which are measured as Resource Units (RUs).
  1,000 tokens = 1 RU, and each RU costs $0.0001 USD.
  Learn more about tokens and tokenization.
• If you are using Jupyter Notebook editor on watsonx.ai, consider selecting a lower runtime environment to avoid high resource consumption and quickly depleting your credits. Notebook runtimes are billed based on Capacity Unit Hours (CUH) at a rate of $1.02 USD per CUH.
  Learn more about capacity unit hours and watsonx.ai Studio pricing plans.

The watsonx.ai platform is pre-configured with only the services required to complete the hackathon. If you notice a permission/access issue for any service or the cloud catalog, then they are not required/available for this hackathon.

These features/capabilities are out of scope for this hackathon:

• Agent Lab (Beta)
• Bring your own model
• Fine tuning models
• AutoAI pipeline
• AI governance
• Evaluation Studio
• SPSS Modeler

DO NOT USE the below listed watsonx.ai models as they are out of scope for the hackathon and can negatively impact the judgment of your project submission.

• llama-3-405b-instruct
• mistral-medium-2505
• mistral-small-3-1-24b-instruct-2503

The hackathon-provisioned IBM Cloud account will be deactivated after the completion of the hackathon. Please plan to save your work at the end of the hackathon.

After successfully joining the IBM Cloud account, you can now access the Prompt Lab on watsonx.ai platform to work with the AI models supported on the platform and build your solution.

1. Log in to the watsonx.ai platform with the email you used to access your IBM Cloud account.
2. After successful authentication, you will see “Welcome to watsonx” widget. You can either take the tour or skip it.
3. Next, you will see the watsonx.ai dashboard. Ensure the name of the account is “xxxxxxx – watsonx” and the region is “Dallas”.

4. Select the Open Prompt Lab button on the “Chat and build prompts” widget.

5. The “Welcome to Prompt Lab” tour will be displayed. You can take the tour to get a quick introduction or skip it.
6. The Prompt Lab Editor opens with a chat window to get you started with the prompt session.

The watsonx.ai Prompt Lab is an easy-to-use prompt engineering interface where you can experiment with prompting different AI foundation models, explore sample prompts, tune model parameters, integrate applications with an API endpoint, and save and share your best prompts.

Take a tour of the Prompt Lab and try the interactive demo.

You can access and use the AI models to build your innovative solution using Prompt Lab.

Learn more about Prompt Lab and how to use it effectively.

In the Prompt Lab, you can experiment with prompting different foundation models, explore sample prompts, as well as save and share your best prompts. The Prompt Lab editor is a great place to experiment and iterate with your prompts.

However, you can also prompt foundation models in watsonx.ai programmatically. Refer to “Programmatic access (API/SDK)” section.

A default AI model will be pre-selected in the Prompt Lab editor. You can either use the same model or change to a different model. To select a different model:

1. Select the AI Model drop-down menu at the top-right of the editor and select View all foundation models.

2. A foundation model selection widget appears. Clear the filters to see all the available models. You can use the filters to choose the right model for your solution building. You can select a model tile to learn about the model and use it. If you are limited to only “Chat” supported models, change the Prompt Lab editor to Structured or Freeform view and try selecting the models to see all the available model options.

Important: DO NOT USE the below listed watsonx.ai models as they are out of scope for the hackathon and can negatively impact the judgment of your project submission.

• mistral-small-3-1-24b-instruct-2503

To understand how models can address your use case, including information on model modalities, supported languages, tuning, and indemnification, see our product documentation on choosing a model.

You can inference the watsonx.ai models with API or SDK requests.

To use the supported watsonx.ai APIs/SDKs, you will need three values: a project ID, an endpoint URL and an API key.

• Go to watsonx.ai home page.
• Scroll down to the “Developer access” section.

• Select the Project or deployment space drop-down and choose the watsonx Hackathon Sandbox option if you are working with that project or select any other listed project that you are working with. A project ID will be displayed. A default watsonx.ai endpoint URL will be displayed for the Dallas region. Ensure the region is always set to Dallas at the top right of the watsonx.ai home page.

• Select the Create API key button. A Create API key widget will be displayed. Enter a name, provide optional description and choose the Delete the leaked key option. Click the Create button.

• An API key will be created successfully. Copy the API key and save it safely to use for calling the API/SDK. You can also download and save the file in a secure path in your system.

There are multiple options to help you get started using watsonx.ai APIs/SDKs.

Option 1: Prompt Code on Prompt Lab

Refer to the access prompt code instructions to learn how to quickly get access to the text generation API within the watsonx.ai Prompt Lab.

Option 2: Different watsonx.ai API capabilities

Explore and leverage different watsonx.ai API capabilities in your solution.

• Chat
• Agent-driven chat
• Tool calling
• Text generation
• Time series
• Text rerank
• Embeddings
• Text extraction

Refer to supported API functionality by AI model here.

To prompt an AI model programmatically, you can view and copy the prompt code by selecting the View code icon </> at the top-right of the prompt lab editor.

The prompt code is available as a Curl, Node.js and Python.

You will require an IAM access token to authorize the prompt code and need to replace ${YOUR_ACCESS_TOKEN} placeholder in the prompt code. You can create an IAM access token using an API key.

• API key:

Refer to Developer access information to get an API key.

• Generate IAM Access Token:

Programmatically generate an IAM access token with the API key using the following cURL command:

curl -X POST 'https://iam.cloud.ibm.com/identity/token' -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=MY_APIKEY'

• curl -X POST → Specifies an HTTP POST request.
• URL ("https://iam.cloud.ibm.com/identity/token") → The endpoint to request an authentication token from IBM Cloud.
• -H "Content-Type: application/x-www-form-urlencoded" → Sets the request header to indicate that the data is sent in form-encoded format.
• -d (Data Payload) → Sends the required data:
• grant_type=urn:ibm:params:oauth:grant-type:apikey → Specifies the OAuth grant type as API Key.
• apikey=MY_IBM_CLOUD_API_KEY → Replace MY_IBM_CLOUD_API_KEY with your actual IBM Cloud API key.

Expected Response:

{

"access_token": "eyJhbGciOiJIUz......sgrKIi8hdFs",

"refresh_token": "not_supported",

"token_type": "Bearer",

"expires_in": 3600,

"expiration": 1473188353,

"scope": “ibm openid”

}

Explore the watsonx.ai supported AI agent framework libraries and tutorials to help you get started building your AI agent solution.

• LangChain
• LangGraph
• LlamaIndex
• CrewAI
• BeeAI
• AutoGen
• Python SDK
• Node.js SDK

Try the quick start exercises and notebooks for sample use cases to get started with using watsonx.ai.

Important notes:

• Refer to developer access information section to use watsonx.ai credentials as you try the exercises.
• Some of the exercises could include the usage of old model version. You can replace them with newer versions for better performance and output. To check the latest supported AI models on watsonx.ai, either follow selecting an AI model on Prompt Lab or refer to supported foundation models on watsonx.ai.
• The hackathon-provisioned cloud accounts do not support solution deployment. You can run your solution deployment locally on your machine and showcase them in your submissions.
• Foundation model inferencing consumes tokens, which are measured as Resource Units (RUs).
  1,000 tokens = 1 RU, and each RU costs $0.0001 USD.
  Learn more about tokens and tokenization.
• If you are using Jupyter Notebook editor on watsonx.ai, consider selecting a lower runtime environment to avoid high resource consumption and quickly depleting your credits. Notebook runtimes are billed based on Capacity Unit Hours (CUH) at a rate of $1.02 USD per CUH.
  Learn more about capacity unit hours and watsonx.ai Studio pricing plans.

watsonx.ai Prompt Lab app templates:

• LangGraph LLM app template with function calling capabilities (base template)
• LlamaIndex Workflow LLM app template with function calling capabilities (base template)
• CrewAI LLM app template with function calling capabilities (base template)
• arXiv Research agent (community template)
• Agentic RAG LangGraph template (community template)

BeeAI Agent Framework:

• BeeAI framework examples

LangChain and LangGraph:

• Create a LangChain AI Agent in Python using watsonx
• Build a RAG agent using LangGraph to answer complex questions
• Build a LangChain agentic RAG system using the Granite model in watsonx.ai
• Use watsonx, and LangChain Agents to perform sequence of actions
• Use watsonx, and LangChain to make a series of calls to a language model
• arXiv Research agent
• Base LangGraph LLM app template with function calling capabilities

LlamaIndex:

• Use watsonx and LlamaIndex for Text-to-SQL task
• Use watsonx, and `llama-3-1-70b-instruct` and LlamaIndex to make simple chat conversation and tool calls
• LlamaIndex Workflow LLM app template with function calling capabilities

CrewAI:

• Leveraging CrewAI and IBM watsonx
• Build an agentic framework with CrewAI memory, i18n, and IBM watsonx.ai
• Base CrewAI LLM app template with function calling capabilities

You can save your Prompt Lab editor session for later use.

1. At the top of the Prompt Lab screen, select the Save work dropdown button and then select the Save as option.

2. A Save your work widget will appear. Select Prompt session under the Asset type option.
3. Enter a name and check the View in project after saving option under the Define details section.
4. Finally, click the Save button. Once you save, you will see the saved work under the Assets tab

You can also save your work as:

• Prompt template to save only the current prompt without its history and selecting a Task suitable for your prompting.
• Notebook to continue prompting on a Jupyter Notebook environment. Prior knowledge of notebooks and Python programming language would be helpful to work with a Jupyter notebook. Read more about notebooks.

Make sure to save any work you want to retain for your records. IBM Cloud accounts will be deactivated at the end of the hackathon. Follow the steps below to save your work:

1. Go to your project’s ‘Overview’ tab.
2. Select the ‘Export or import project’ drop down below the Bell icon in the top menu bar.
3. Click the ‘Export project’ option. This will open ‘Export project to desktop’ screen.
4. Select all the assets shown in your project (Work saved as Project session cannot be exported) and click ‘Export’ on the bottom-right of the screen.
5. The next screen will ask for confirmation that all sensitive information has been removed.
6. Click on ‘Continue export’.
7. The download (zip) will be initiated, and the file will be saved on your computer.