A newer version of the Gradio SDK is available: 6.20.0
Agent instructions
Use agent instructions to provide always-on guidance that AWS DevOps Agent applies to every session. A session is a single conversation or investigation with an agent. On the Knowledge page in your Agent Space Operator Web App, choose the Instructions tab to set instructions that apply to all agents, or set instructions for a specific managed agent such as Chat or Incident triage. These instructions are stored as an AGENTS.md file. Unlike DevOps Agent Skills, which load on demand when the agent matches a skill description to the current task, agent instructions are always present from the start of every session, regardless of what the agent is working on.
What are agent instructions
Agent instructions provide unconditional, always-on guidance for your agents. At the start of every session, the agent service retrieves the instructions configured for your Agent Space and injects their content directly into the agent system prompt. The agent does not decide whether to load them; they are always present.
Each agent session receives instructions from both the global instructions and the relevant agent-specific instructions.
Agent instructions are stored as AGENTS.md files and differ from DevOps Agent Skills in several important ways:
| Aspect | Skill | Agent instructions (AGENTS.md) |
|---|---|---|
| Name and description | Required | Not applicable |
| Content format | Markdown or ZIP bundle | Markdown only |
| Resource files | Supported | Not supported |
| Context injection | On demand (agent decides via skill description matching) | Always (unconditional, every session) |
| Uniqueness | Multiple per Agent Space | One per agent |
Why use agent instructions
Agent instructions give you a reliable way to ensure certain guidance is always in context, without depending on the agent's skill-loading decisions.
Key benefits:
- Predictability: Instructions are always present, regardless of what task the agent is working on.
- Guaranteed coverage: Unlike Skills, which the agent may or may not load depending on task relevance, agent instructions are always injected at the start of every session.
- Standing policies: Use agent instructions for standing operational policies, security guidelines, coding standards, or any guidance that must apply to every session without exception.
- Targeted scope: You can apply instructions to all agent types at once using global instructions, or restrict instructions to a specific agent type.
How agent instructions work
When a session starts, the agent service retrieves the instructions configured for your Agent Space and injects their content into the agent system prompt before the session begins. This happens automatically for every session.
Each new session loads the instructions fresh at startup. If you update your instructions, the change takes effect immediately for sessions that start after you save.
Agent type scoping
Scoping controls which agent sessions receive a given set of instructions:
- Global instructions: Applies to all agent types in your Agent Space.
- Agent-specific: Applies only to sessions of the selected agent type.
The managed agents available for agent-specific instructions are:
- Chat - Ad-hoc questions and requests during chat sessions.
- Incident triage - Alarm filtering, severity classification, and initial scoping.
- Incident RCA - Root cause analysis with evidence collection and validation.
- Incident mitigation - Short-term remediation and long-term fix recommendations.
- Evaluation - Agent performance scoring and policy compliance checks.
Content size guidance
- Hard limit: 25 KB
- Recommended size: 120 lines
Focus your instructions on guidance that must be present in every session. For specialized investigation procedures, consider using DevOps Agent Skills instead.
Example
# Agent Instructions
## Investigation approach
- Always check CloudWatch alarms and recent deployments before proposing a root cause.
## Response format
- Lead with a one-sentence summary of findings before listing details.
- Include the AWS region and resource identifier for any resource you reference.
- Use bullet points for lists of findings or recommendations.
## Security
- Never log, display, or suggest storing credentials or secrets in plaintext.
- When recommending IAM changes, follow least-privilege principles.
Setting agent instructions
Each agent has exactly one set of instructions. When you save new content, it overwrites the existing content for that agent.
To set global instructions (applies to all agents):
- Navigate to the Knowledge page in your Agent Space Operator Web App.
- Choose the Instructions tab.
- Choose View next to All agents.
- Enter your markdown instructions in the editor.
- Choose Save.
To set instructions for a specific agent:
- Navigate to the Knowledge page in your Agent Space Operator Web App.
- Choose the Instructions tab.
- Choose View next to the agent you want to configure.
- Enter your markdown instructions in the editor.
- Choose Save.
Managing agent instructions
Viewing instructions: Navigate to the Knowledge page, choose the Instructions tab, and choose View next to the agent.
Editing instructions: Open the agent, modify the content, and choose Save.
Uploading instructions from a file: Choose the Upload button to upload a markdown file.
Downloading instructions: Choose the Download button to download the current content.
Deleting instructions: Choose the Delete button and confirm the deletion.