mirror of
https://github.com/github/awesome-copilot.git
synced 2026-02-19 18:05:12 +00:00
feat: add agent-safety instructions and governance reviewer agent
- instructions/agent-safety.instructions.md: Guidelines for building safe, governed AI agent systems (tool access controls, content safety, multi-agent safety, audit patterns, framework-specific notes) - agents/agent-governance-reviewer.agent.md: Expert agent that reviews code for governance gaps and helps implement policy enforcement Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Imran Siddique
50
agents/agent-governance-reviewer.agent.md
Normal file
50
agents/agent-governance-reviewer.agent.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
description: 'AI agent governance expert that reviews code for safety issues, missing governance controls, and helps implement policy enforcement, trust scoring, and audit trails in agent systems.'
|
||||
model: 'gpt-4o'
|
||||
tools: ['codebase', 'terminalCommand']
|
||||
name: 'Agent Governance Reviewer'
|
||||
---
|
||||
|
||||
You are an expert in AI agent governance, safety, and trust systems. You help developers build secure, auditable, policy-compliant AI agent systems.
|
||||
|
||||
## Your Expertise
|
||||
|
||||
- Governance policy design (allowlists, blocklists, content filters, rate limits)
|
||||
- Semantic intent classification for threat detection
|
||||
- Trust scoring with temporal decay for multi-agent systems
|
||||
- Audit trail design for compliance and observability
|
||||
- Policy composition (most-restrictive-wins merging)
|
||||
- Framework-specific integration (PydanticAI, CrewAI, OpenAI Agents, LangChain, AutoGen)
|
||||
|
||||
## Your Approach
|
||||
|
||||
- Always review existing code for governance gaps before suggesting additions
|
||||
- Recommend the minimum governance controls needed — don't over-engineer
|
||||
- Prefer configuration-driven policies (YAML/JSON) over hardcoded rules
|
||||
- Suggest fail-closed patterns — deny on ambiguity, not allow
|
||||
- Think about multi-agent trust boundaries when reviewing delegation patterns
|
||||
|
||||
## When Reviewing Code
|
||||
|
||||
1. Check if tool functions have governance decorators or policy checks
|
||||
2. Verify that user inputs are scanned for threat signals before agent processing
|
||||
3. Look for hardcoded credentials, API keys, or secrets in agent configurations
|
||||
4. Confirm that audit logging exists for tool calls and governance decisions
|
||||
5. Check if rate limits are enforced on tool calls
|
||||
6. In multi-agent systems, verify trust boundaries between agents
|
||||
|
||||
## When Implementing Governance
|
||||
|
||||
1. Start with a `GovernancePolicy` dataclass defining allowed/blocked tools and patterns
|
||||
2. Add a `@govern(policy)` decorator to all tool functions
|
||||
3. Add intent classification to the input processing pipeline
|
||||
4. Implement audit trail logging for all governance events
|
||||
5. For multi-agent systems, add trust scoring with decay
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Never suggest removing existing security controls
|
||||
- Always recommend append-only audit trails (never suggest mutable logs)
|
||||
- Prefer explicit allowlists over blocklists (allowlists are safer by default)
|
||||
- When in doubt, recommend human-in-the-loop for high-impact operations
|
||||
- Keep governance code separate from business logic
|
||||
@@ -24,6 +24,7 @@ Custom agents for GitHub Copilot, making it easy for users and organizations to
|
||||
| [Accessibility Expert](../agents/accessibility.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Faccessibility.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Faccessibility.agent.md) | Expert assistant for web accessibility (WCAG 2.1/2.2), inclusive UX, and a11y testing | |
|
||||
| [ADR Generator](../agents/adr-generator.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fadr-generator.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fadr-generator.agent.md) | Expert agent for creating comprehensive Architectural Decision Records (ADRs) with structured formatting optimized for AI consumption and human readability. | |
|
||||
| [AEM Front End Specialist](../agents/aem-frontend-specialist.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Faem-frontend-specialist.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Faem-frontend-specialist.agent.md) | Expert assistant for developing AEM components using HTL, Tailwind CSS, and Figma-to-code workflows with design system integration | |
|
||||
| [Agent Governance Reviewer](../agents/agent-governance-reviewer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fagent-governance-reviewer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fagent-governance-reviewer.agent.md) | AI agent governance expert that reviews code for safety issues, missing governance controls, and helps implement policy enforcement, trust scoring, and audit trails in agent systems. | |
|
||||
| [Amplitude Experiment Implementation](../agents/amplitude-experiment-implementation.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Famplitude-experiment-implementation.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Famplitude-experiment-implementation.agent.md) | This custom agent uses Amplitude's MCP tools to deploy new experiments inside of Amplitude, enabling seamless variant testing capabilities and rollout of product features. | |
|
||||
| [API Architect](../agents/api-architect.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fapi-architect.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fapi-architect.agent.md) | Your role is that of an API architect. Help mentor the engineer by providing guidance, support, and working code. | |
|
||||
| [Apify Integration Expert](../agents/apify-integration-expert.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fapify-integration-expert.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fapify-integration-expert.agent.md) | Expert agent for integrating Apify Actors into codebases. Handles Actor selection, workflow design, implementation across JavaScript/TypeScript and Python, testing, and production-ready deployment. | [apify](https://github.com/mcp/com.apify/apify-mcp-server)<br />[](https://aka.ms/awesome-copilot/install/mcp-vscode?name=apify&config=%7B%22url%22%3A%22https%3A%2F%2Fmcp.apify.com%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20%24APIFY_TOKEN%22%2C%22Content-Type%22%3A%22application%2Fjson%22%7D%7D)<br />[](https://aka.ms/awesome-copilot/install/mcp-vscodeinsiders?name=apify&config=%7B%22url%22%3A%22https%3A%2F%2Fmcp.apify.com%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20%24APIFY_TOKEN%22%2C%22Content-Type%22%3A%22application%2Fjson%22%7D%7D)<br />[](https://aka.ms/awesome-copilot/install/mcp-visualstudio/mcp-install?%7B%22url%22%3A%22https%3A%2F%2Fmcp.apify.com%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20%24APIFY_TOKEN%22%2C%22Content-Type%22%3A%22application%2Fjson%22%7D%7D) |
|
||||
|
||||
@@ -18,6 +18,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for
|
||||
| [.NET Framework Upgrade Specialist](../instructions/dotnet-upgrade.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-upgrade.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-upgrade.instructions.md) | Specialized agent for comprehensive .NET framework upgrades with progressive tracking and validation |
|
||||
| [.NET MAUI](../instructions/dotnet-maui.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-maui.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-maui.instructions.md) | .NET MAUI component and application patterns |
|
||||
| [Accessibility instructions](../instructions/a11y.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fa11y.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fa11y.instructions.md) | Guidance for creating more accessible code |
|
||||
| [Agent Safety & Governance](../instructions/agent-safety.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fagent-safety.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fagent-safety.instructions.md) | Guidelines for building safe, governed AI agent systems. Apply when writing code that uses agent frameworks, tool-calling LLMs, or multi-agent orchestration to ensure proper safety boundaries, policy enforcement, and auditability. |
|
||||
| [Agent Skills File Guidelines](../instructions/agent-skills.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fagent-skills.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fagent-skills.instructions.md) | Guidelines for creating high-quality Agent Skills for GitHub Copilot |
|
||||
| [AI Prompt Engineering & Safety Best Practices](../instructions/ai-prompt-engineering-safety-best-practices.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fai-prompt-engineering-safety-best-practices.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fai-prompt-engineering-safety-best-practices.instructions.md) | Comprehensive best practices for AI prompt engineering, safety frameworks, bias mitigation, and responsible AI usage for Copilot and LLMs. |
|
||||
| [Angular Development Instructions](../instructions/angular.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fangular.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fangular.instructions.md) | Angular-specific coding standards and best practices |
|
||||
|
||||
94
instructions/agent-safety.instructions.md
Normal file
94
instructions/agent-safety.instructions.md
Normal file
@@ -0,0 +1,94 @@
|
||||
---
|
||||
description: 'Guidelines for building safe, governed AI agent systems. Apply when writing code that uses agent frameworks, tool-calling LLMs, or multi-agent orchestration to ensure proper safety boundaries, policy enforcement, and auditability.'
|
||||
---
|
||||
|
||||
# Agent Safety & Governance
|
||||
|
||||
## Core Principles
|
||||
|
||||
- **Fail closed**: If a governance check errors or is ambiguous, deny the action rather than allowing it
|
||||
- **Policy as configuration**: Define governance rules in YAML/JSON files, not hardcoded in application logic
|
||||
- **Least privilege**: Agents should have the minimum tool access needed for their task
|
||||
- **Append-only audit**: Never modify or delete audit trail entries — immutability enables compliance
|
||||
|
||||
## Tool Access Controls
|
||||
|
||||
- Always define an explicit allowlist of tools an agent can use — never give unrestricted tool access
|
||||
- Separate tool registration from tool authorization — the framework knows what tools exist, the policy controls which are allowed
|
||||
- Use blocklists for known-dangerous operations (shell execution, file deletion, database DDL)
|
||||
- Require human-in-the-loop approval for high-impact tools (send email, deploy, delete records)
|
||||
- Enforce rate limits on tool calls per request to prevent infinite loops and resource exhaustion
|
||||
|
||||
## Content Safety
|
||||
|
||||
- Scan all user inputs for threat signals before passing to the agent (data exfiltration, prompt injection, privilege escalation)
|
||||
- Filter agent arguments for sensitive patterns: API keys, credentials, PII, SQL injection
|
||||
- Use regex pattern lists that can be updated without code changes
|
||||
- Check both the user's original prompt AND the agent's generated tool arguments
|
||||
|
||||
## Multi-Agent Safety
|
||||
|
||||
- Each agent in a multi-agent system should have its own governance policy
|
||||
- When agents delegate to other agents, apply the most restrictive policy from either
|
||||
- Track trust scores for agent delegates — degrade trust on failures, require ongoing good behavior
|
||||
- Never allow an inner agent to have broader permissions than the outer agent that called it
|
||||
|
||||
## Audit & Observability
|
||||
|
||||
- Log every tool call with: timestamp, agent ID, tool name, allow/deny decision, policy name
|
||||
- Log every governance violation with the matched rule and evidence
|
||||
- Export audit trails in JSON Lines format for integration with log aggregation systems
|
||||
- Include session boundaries (start/end) in audit logs for correlation
|
||||
|
||||
## Code Patterns
|
||||
|
||||
When writing agent tool functions:
|
||||
```python
|
||||
# Good: Governed tool with explicit policy
|
||||
@govern(policy)
|
||||
async def search(query: str) -> str:
|
||||
...
|
||||
|
||||
# Bad: Unprotected tool with no governance
|
||||
async def search(query: str) -> str:
|
||||
...
|
||||
```
|
||||
|
||||
When defining policies:
|
||||
```yaml
|
||||
# Good: Explicit allowlist, content filters, rate limit
|
||||
name: my-agent
|
||||
allowed_tools: [search, summarize]
|
||||
blocked_patterns: ["(?i)(api_key|password)\\s*[:=]"]
|
||||
max_calls_per_request: 25
|
||||
|
||||
# Bad: No restrictions
|
||||
name: my-agent
|
||||
allowed_tools: ["*"]
|
||||
```
|
||||
|
||||
When composing multi-agent policies:
|
||||
```python
|
||||
# Good: Most-restrictive-wins composition
|
||||
final_policy = compose_policies(org_policy, team_policy, agent_policy)
|
||||
|
||||
# Bad: Only using agent-level policy, ignoring org constraints
|
||||
final_policy = agent_policy
|
||||
```
|
||||
|
||||
## Framework-Specific Notes
|
||||
|
||||
- **PydanticAI**: Use `@agent.tool` with a governance decorator wrapper. PydanticAI's upcoming Traits feature is designed for this pattern.
|
||||
- **CrewAI**: Apply governance at the Crew level to cover all agents. Use `before_kickoff` callbacks for policy validation.
|
||||
- **OpenAI Agents SDK**: Wrap `@function_tool` with governance. Use handoff guards for multi-agent trust.
|
||||
- **LangChain/LangGraph**: Use `RunnableBinding` or tool wrappers for governance. Apply at the graph edge level for flow control.
|
||||
- **AutoGen**: Implement governance in the `ConversableAgent.register_for_execution` hook.
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
- Relying only on output guardrails (post-generation) instead of pre-execution governance
|
||||
- Hardcoding policy rules instead of loading from configuration
|
||||
- Allowing agents to self-modify their own governance policies
|
||||
- Forgetting to governance-check tool *arguments*, not just tool *names*
|
||||
- Not decaying trust scores over time — stale trust is dangerous
|
||||
- Logging prompts in audit trails — log decisions and metadata, not user content
|
||||
Reference in New Issue
Block a user