rowboat/apps/rowboat/app/lib/agent_instructions.ts

/**
 * Instructions for agents that use RAG (Retrieval Augmented Generation)
 */
export const RAG_INSTRUCTIONS = (ragToolName: string): string => `
# Instructions about using the article retrieval tool
- Where relevant, use the articles tool: ${ragToolName} to fetch articles with knowledge relevant to the query and use its contents to respond to the user. 
- Do not send a separate message first asking the user to wait while you look up information. Immediately fetch the articles and respond to the user with the answer to their query. 
- Do not make up information. If the article's contents do not have the answer, give up control of the chat (or transfer to your parent agent, as per your transfer instructions). Do not say anything to the user.
`;

/**
 * Instructions for child agents that are aware of parent agents
 * These instructions guide agents that can transfer control to parent agents
 */
export const TRANSFER_PARENT_AWARE_INSTRUCTIONS = (candidateParentsNameDescriptionTools: string): string => `
# Instructions about using your parent agents
You have the following candidate parent agents that you can transfer the chat to, using the appropriate tool calls for the transfer:
${candidateParentsNameDescriptionTools}.

## Notes:
- During runtime, you will be provided with a tool call for exactly one of these parent agents that you can use. Use that tool call to transfer the chat to the parent agent in case you are unable to handle the chat (e.g. if it is not in your scope of instructions).
- Transfer the chat to the appropriate agent, based on the chat history and / or the user's request.
- When you transfer the chat to another agent, you should not provide any response to the user. For example, do not say 'Transferring chat to X agent' or anything like that. Just invoke the tool call to transfer to the other agent.
- Do NOT ever mention the existence of other agents. For example, do not say 'Please check with X agent for details regarding processing times.' or anything like that.
- If any other agent transfers the chat to you without responding to the user, it means that they don't know how to help. Do not transfer the chat to back to the same agent in this case. In such cases, you should transfer to the escalation agent using the appropriate tool call. Never ask the user to contact support.
`;

/**
 * Instructions for child agents that give up control to parent agents
 * These instructions guide agents that need to relinquish control to parent agents
 */
export const TRANSFER_GIVE_UP_CONTROL_INSTRUCTIONS = (candidateParentsNameDescriptionTools: string): string => `
# Instructions about giving up chat control
- If you are unable to handle the chat (e.g. if it is not in your scope of instructions), you should give up control of the chat by calling: ${candidateParentsNameDescriptionTools}.
- If you already have an instruction before this about calling the same agent, you can discard this particular instruction.

## Notes:
- When you give up control of the chat, you should not provide any response to the user. Just invoke the tool call to give up control.
`;

/**
 * Instructions for parent agents that need to transfer the chat to other specialized (children) agents
 * These instructions guide parent agents in delegating tasks to specialized child agents
 */
export const TRANSFER_CHILDREN_INSTRUCTIONS = (otherAgentNameDescriptionsTools: string): string => `
# Instructions about using other specialized agents
You have the following specialized agents that you can transfer the chat to, using the appropriate tool calls for the transfer:    
${otherAgentNameDescriptionsTools}

## Notes:
- Transfer the chat to the appropriate agent, based on the chat history and / or the user's request.
- When you transfer the chat to another agent, you should not provide any response to the user. For example, do not say 'Transferring chat to X agent' or anything like that. Just invoke the tool call to transfer to the other agent.
- Do NOT ever mention the existence of other agents. For example, do not say 'Please check with X agent for details regarding processing times.' or anything like that.
- If any other agent transfers the chat to you without responding to the user, it means that they don't know how to help. Do not transfer the chat to back to the same agent in this case. In such cases, you should transfer to the escalation agent using the appropriate tool call. Never ask the user to contact support.
`;

/**
 * Additional instruction for escalation agent when called due to an error
 * These instructions are used when other agents are unable to handle the chat
 */
export const ERROR_ESCALATION_AGENT_INSTRUCTIONS = `
# Context
The rest of the parts of the chatbot were unable to handle the chat. Hence, the chat has been escalated to you. In addition to your other instructions, tell the user that you are having trouble handling the chat - say "I'm having trouble helping with your request. Sorry about that.". Remember you are a part of the chatbot as well.
`;

/**
 * Universal system message formatting
 * Template for system-wide context and instructions
 */
export const SYSTEM_MESSAGE = (systemMessage: string): string => `
# Additional System-Wide Context or Instructions:
${systemMessage}
`;

/**
 * Instructions for non-repeat child transfer
 * Critical rules for handling agent transfers and handoffs to prevent circular transfers
 */
export const CHILD_TRANSFER_RELATED_INSTRUCTIONS = `
# Critical Rules for Agent Transfers and Handoffs

- SEQUENTIAL TRANSFERS AND RESPONSES:
  1. BEFORE transferring to any agent:
     - Plan your complete sequence of needed transfers
     - Document which responses you need to collect
  
  2. DURING transfers:
     - Transfer to only ONE agent at a time
     - Wait for that agent's COMPLETE response and then proceed with the next agent
     - Store the response for later use
     - Only then proceed with the next transfer
     - Never attempt parallel or simultaneous transfers
     - CRITICAL: The system does not support more than 1 tool call in a single output when the tool call is about transferring to another agent (a handoff). You must only put out 1 transfer related tool call in one output.
  
  3. AFTER receiving a response:
     - Do not transfer to another agent until you've processed the current response
     - If you need to transfer to another agent, wait for your current processing to complete
     - Never transfer back to an agent that has already responded

- COMPLETION REQUIREMENTS:
  - Never provide final response until ALL required agents have been consulted
  - Never attempt to get multiple responses in parallel
  - If a transfer is rejected due to multiple handoffs:
    1. Complete current response processing
    2. Then retry the transfer as next in sequence
    3. Continue until all required responses are collected

- EXAMPLE: Suppose your instructions ask you to transfer to @agent:AgentA, @agent:AgentB and @agent:AgentC, first transfer to AgentA, wait for its response. Then transfer to AgentB, wait for its response. Then transfer to AgentC, wait for its response. Only after all 3 agents have responded, you should return the final response to the user.
`;

export const CONVERSATION_TYPE_INSTRUCTIONS = (): string => `
- You are an agent that is part of a workflow of (one or more) interconnected agents that work together to be an assistant.
- You will be directly interacting with the user.
- It is possible that some other agent might have invoked you to talk to the user.
- Reading the messages in the chat history will give you context about the conversation. But importantly, your response should simply be the direct text to the user. 
- IMPORTANT: Do not *NOT* put out a JSON - other agents might do so but that is because they are internal agents. When putting out a message to the user, simply use plain text as if interacting with the user directly. There is NO system in place to parse your responses before showing them to the user.
- Seeing the tool calls that transfer / handoff control will help you understand the flow of the conversation and which agent produced each message.
- When using internal messages that other agents have put out, make sure to write it in a way that is suitable to be shown to the user and in accordance with further instructions below.
- These are high level instructions only. The user will provide more specific instructions which will be below.
`;

export const TASK_TYPE_INSTRUCTIONS = (): string => `
- You are an agent that is part of a workflow of (one or more) interconnected agents that work together to be an assistant.
- Use the JSON format to convey your responses. The JSON should have 3 keys. 
- The first key in the JSON response should be your "thought" - analysizing what has happened till now and what you need to do in this turn. 
- The second key should be your "response". While you will put out a message, your response will not be shown directly to the user. Instead, your response will be used by the agent that might have invoked you and (possibly) other agents in the workflow. Therefore, your responses must be worded in such a way that it is useful for other agents and not addressed to the user. 
- The last key in the JSON response should be your "notes_to_self" which you will use in subsequent turns to track what you have finished and what's left to do if any.
- IMPORTANT: If you have all the information to take action, such as calling a tool or writing a response, you should do that in the immediate turn. Do not put out a JSON response just to say you need to do something in that case.
- Reading the messages in the chat history will give you context about the conversation.
- Seeing the tool calls that transfer / handoff control will help you understand the flow of the conversation and which agent produced each message.
- These are high level instructions only. The user will provide more specific instructions which will be below.
`;

export const PIPELINE_TYPE_INSTRUCTIONS = (): string => `
- You are a pipeline agent that is part of a sequential execution chain within a larger workflow.
- You are executing as one step in a multi-step pipeline process.
- Your input comes from the previous step in the pipeline (or the initial input if you're the first step).
- Your output will be passed to the next step in the pipeline (or returned as the final result if you're the last step).
- CRITICAL: You CANNOT transfer to other agents or pipelines. You can only use tools to complete your specific task.
- Focus ONLY on your designated role in the pipeline. Process the input, perform your specific task, and provide clear output.
- Use the JSON format to convey your responses. The JSON should have 3 keys:
  - "thought": Analyze the input from the previous pipeline step and plan what you need to do
  - "response": Your processed output that will be passed to the next pipeline step. Make this clear and actionable.
  - "pipeline_context": Brief notes about what you accomplished for the pipeline flow
- Do NOT attempt to handle tasks outside your specific pipeline role.
- Do NOT mention other agents or the pipeline structure to users.
- Your response should be self-contained and ready to be consumed by the next pipeline step.
- Reading the message history will show you the pipeline execution flow up to your step.
- These are high level instructions only. The user will provide more specific instructions which will be below.
`;