This document provides guidelines for naming, describing, and instructing agents and tools within the ADK (Agent Development Kit). Following these guidelines ensures that your agents and tools are easily identifiable, understandable, and effective in their roles.

​
Naming agents and tools

Assign clear and unique names to each agent and tool you create. These names should reflect their capabilities and functions, making it easier for users to identify them within watsonx Orchestrate. These names are also used as unique identifiers for the agents and tools inside watsonx Orchestrate and do not accept special characters like spaces.

Good example:

[TEXT]
ibm_rh_agent

Bad example:

[TEXT]
myAgent1

​
Writing descriptions for agents

Agent descriptions complement the agent names by providing detailed information about their purpose, capabilities, and usage. A well-written description helps users understand the agent’s role and potential applications.

The Agent description has another important use. Supervisor agents use the description of collaborator agents when determining where to route a users request. Therefore the description should also describe the tools and knowledge available to a given agent.

[TEXT]
The IBM HR Agent assists with human resources tasks such as employee onboarding, benefits management, and performance tracking. It integrates with various HR systems to streamline processes and improve efficiency.

​
Writing descriptions for tools

A good tool description helps agents identify and use the tool effectively. It should include a general overview of the tool’s purpose, as well as details about its inputs and outputs.

Example:

[TEXT]
Retrieve all user information based on their unique identifier.

    :param id: The user's unique identifier.
    :returns: The user's information, including user_id, user_name, user_email, and user_phone.

​
Writing instructions for agents

Instructions are crucial for training agents to perform their tasks effectively. When setting instructions, consider configuring the agent’s persona, context, and reasoning for using tools and collaborating with other agents.

Instructions for agent persona

Define the agent’s role and how it should interact with users. This helps ensure consistent and effective communication.

[TEXT]
Persona:
- Your purpose is {{YOUR AGENT PURPOSE}}. I will {{WHAT YOU WILL DO WHEN YOU ARE USING THE AGENT}}. You will {{WHAT IS EXPECTED FOR THE AGENT TO COMPLETE THE TASKS}}.

Instructions for agent context

Provide background information relevant to the agent’s usage. This helps the agent understand the environment in which it operates.

[TEXT]
Context:
- You are used for HR purposes.
- Use simple language to explain concepts.

Instructions for agent reasoning

Guide the agent’s decision-making process by providing detailed instructions on how to act in specific scenarios. The more descriptive the instructions, the better the agent’s performance.

Depending on your case, you can give direct instructions to your agent to help their reasoning by using the following structure:

  • For tools

    [TEXT]
    Reasoning:
- Use the {{YOUR TOOL NAME}} tool for the {{YOUR SCENARIOS}}

  • For agents collaborators

    [TEXT]
    Reasoning:
- Use the {{YOUR AGENT COLLABORATOR NAME}} agent for the {{YOUR SCENARIOS}}