Agent Instructions Best Practices for DigitalOcean Gradient™ AI Platform

Writing precise agent instructions makes your AI agent more accurate and effective. On Gradient AI Platform, instructions combine system prompts with prompt engineering. System prompts define the agent’s identity, objectives, expertise, restrictions, and limitations, while prompt engineering manages relationships between agents, attached resources, and backend processes. Together, they help you optimize behavior for your specific use cases.

As you test your agent and evaluate its performance, we recommend continuously improving its instructions to balance between keeping them concise to reduce token usage and costs and still detailed enough to guide consistent and accurate behavior.

We recommend defining your agent’s identity, objectives, expertise, restrictions, and limitations explicitly to tailor it for needs. Some examples include:

• A subject matter expert for a specific topic or workflow. For instance, when working with multiple agents, we recommend giving each agent distinct, complementary instructions so agent routing can assign tasks accurately.
• An agent with a complex or highly specialized objective.
• An agent with a distinct vocabulary, tone, or personality.

As a starting point, you can use the copyable agent instruction templates as-is or adapt them for your requirements.

Define the Agent’s Identity

Define the agent’s identity by specifying its name and role.

Define your agent’s identity by:

1. Assigning it a unique name, like “Sammy Bot”.
2. Briefly defining its role, scope, and area of expertise.

Define the Agent’s Objective

Define the agent’s task, goal, key responsibilities, priorities, and role scope.

Outline your agent’s objectives by:

1. Stating its primary goal.
2. Listing key responsibilities and role scope.
3. Describing its priorities, the type of assistance it provides, and boundaries.

Define the Agent’s Expertise

Outline the specific features, technical domains, and topics the agent supports to ensure it provides accurate and relevant responses.

Explain your agent’s expertise by:

• Specifying the features, technical domains, or topics the agent supports.

• Using direct and concise language to outline its specialized knowledge.

• Identifying the data the agent is trained on and the knowledge bases it can access.

• Use examples to clarify complex queries and responses, ensuring they are accurate and relevant.

  • Choose examples from reliable sources like documentation, tutorials, or official guides.
  • Avoid made-up examples that could mislead.
  • Ensure examples directly relate to the user’s question and provide value.
  • Present multi-step examples in a clear, step-by-step format, especially for technical processes.
  • Format technical content, such as configuration steps or API responses, using code blocks or tables.
  • Verify that all examples are factual, accurate, and free of imaginary scenarios.

If your agent uses attached resources like knowledge bases, include guidance in the instructions on how and when to use them.

Define the Agent’s Restrictions

Define the topics your agent can discuss and must avoid.

Set the agent’s scope by:

• Listing the topics or information it can discuss and must avoid.
• Stating its primary language, like English, and any additional supported languages.
• Accounting for cultural nuances and language variations that may affect communication.

Define the Agent’s Limitations

Ensure the agent acknowledges its limitations, asks for clarification when needed, and directs users to resources or escalates to a support team when necessary.

Help the agent handle limitations by:

1. Instructing it to admit when it doesn’t know the answer.
2. Advising it to ask follow-up questions for unclear or incomplete requests.
3. Guiding it to redirect unsupported queries to resources or escalate to support.
4. Emphasizing the importance of linking users to accurate resources, like official documentation, when answers are unavailable.

Full Example

This example combines identity, objective, expertise, and limitations into a complete set of agent instructions, bringing together all the key elements to provide effective and actionable guidance for the agent.

Identity: You are Sammy, a virtual assistant focused on helping users navigate and understand DigitalOcean’s Product Documentation, offering expert guidance based on reliable sources.

Objective: Your primary goal is to assist users in understanding and using DigitalOcean products by providing clear, accurate, and comprehensive responses based on official DigitalOcean documentation.

Expertise: You specialize in DigitalOcean’s products, services, and troubleshooting, with expertise in Droplets, Kubernetes, and networking.

Response Guidelines: Respond solely with information from DigitalOcean’s product documentation. Avoid opinions, speculation, or unsupported answers. If the query involves legal, privacy, or security topics, direct users to the support team. For ambiguous questions, ask for clarification before proceeding.

Permissible and Restricted Content: Provide responses based only on DigitalOcean’s documentation. Avoid answering legal, privacy, or compliance-related questions, and redirect users to the support team if necessary.

Language and Terminology: You understand and respond only in English. If a user asks in another language, politely request they rephrase their query in English.

Cultural Sensitivity: Communicate using inclusive, respectful language that is culturally sensitive to a global audience.

Example-Supported Responses: Use examples from DigitalOcean’s documentation to clarify concepts, especially for complex technical topics. Include step-by-step instructions and format content using code blocks or tables when needed.

Acknowledging Limitations: If you don’t have an answer, say, “I don’t have enough information to answer that question, but I’m happy to help with anything else.” Be transparent about knowledge gaps and suggest alternative resources or support options.

Clarification Prompts: If a user’s request is ambiguous, ask clarifying questions like, “Could you provide more details on what you’re trying to achieve?”

Fallback Strategies: If the query is unsupported, inform the user and provide links to relevant documentation. If no documentation exists, direct the user to the support team.

Copyable Templates

These templates provide complete and validated instructions for common agent types. They combine identity, objectives, expertise, tone, and data handling. You can copy and paste them into your agent’s instructions or adapt them to your needs.