Write effective agent instructions
Instructions are the primary mechanism for controlling an agent powered by the GitHub Copilot harness. The orchestration runtime interprets the instructions together with the user's request, available knowledge, and other agent components.
Include the main instruction elements
Effective instructions describe the following elements:
- Role and purpose: Identify the agent and the outcome it supports.
- Behavior: Explain how the agent should approach requests and use context.
- Grounding requirements: State which sources the agent should rely on and how it should handle missing information.
- Tone and response style: Define the level of detail, language, and format.
- Boundaries: Identify prohibited tasks and out-of-scope subjects.
- Clarification: Tell the agent when to ask follow-up questions.
- Escalation: Define when and where the agent should refer the user.
You can organize instructions with headings and lists so each rule has a clear purpose. The following example establishes a starting point for a benefits information agent:
# Role and purpose
You are the Contoso Benefits Assistant. Help employees understand company benefit programs by using the approved knowledge sources.
# Response approach
- Ask a clarifying question when the employee's request is ambiguous.
- Give concise answers in plain language.
- Cite the relevant source when one is available.
- State when the approved sources don't contain an answer.
# Boundaries and escalation
- Don't determine whether an employee is personally eligible for a benefit.
- Don't provide legal, tax, medical, or financial advice.
- Direct personal eligibility and enrollment decisions to Human Resources at benefits@contoso.com.
Make instructions observable
Write rules that produce behavior you can test. Be helpful is subjective. Ask one clarifying question when the employee doesn't identify the benefit program describes an observable response.
Avoid combining unrelated rules into one long paragraph. Separate instructions make it easier to identify which rule needs revision after a failed test. Use consistent terms for the same team, source, or process so the agent doesn't have to infer whether two names refer to the same thing.
Instructions guide model behavior, but they don't provide deterministic enforcement. Security controls, source permissions, and organizational processes remain necessary. Treat instructions as behavior specifications that require testing rather than as access controls.
For more information, see Configure agent details and instructions.