Skip to main content
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. Names written in snake_case tend to perform best. Good example:
TEXT
name: ibm_historical_knowledge_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. In Python tools, descriptions are defined in docstrings, following Google-style docstrings. Example:
TEXT
Retrieves all user information based on their unique identifier.

Args:
    id (str): The user's unique identifier.

Returns:
    dict: 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}}

​
Designing agents and tools for best performance

When designing agents and tools, aim for balanced complexity. Components that are too simple may lack utility, while overly complex designs can reduce the model’s ability to reason effectively.

​
Guidelines for Agents

  • Agents using LLaMA-based LLMs perform best with 10 or fewer tools or collaborators.
  • For complex use cases requiring many tools, break the problem into smaller subproblems and assign them to collaborator agents.
  • This limit may vary for more powerful models.

​
Guidelines for Tools

  • Keep input and output schemas as simple as possible.
  • Avoid tools with:
    • A large number of input parameters.
    • Parameters with deeply nested or complex data types.
  • Complex schemas make it harder for the LLM to use the tool effectively.