agentleFS
Sign inStart free
MicrosoftKnown publishermicrosoft/iq-samples/refund-agent-a365/.github/copilot-instructions.md

iq-samples / refund-agent-a365

Copilot instructions7 starsChanged 5 months agoMITView on GitHub

This sample is part of the microsoft/iq-samples repo. Only read and modify files within this folder (refund-agent-a365/). Do not touch other samples or root-level governance files (LICENSE, CODEOFCONDUCT.md, SECURITY.md, SUPPORT.md). This is a Python agent that wraps an Microsoft Foundry agent (with Fabric Data Agent + Work IQ tools) and publishes it to Microsoft Teams / M365 Copilot via the Microsoft Agent 365 (A365) SDK. The Foundry agent handles all intelligence; this project is the A365 hosting wrapper that adds…

  • Reads credentials
  • Installs packages

We split this copilot-instructions.md into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    IMPORTANT: When encountering any errors during setup, deployment, or runtime, always check TROUBLESHOOTING.md first before debugging blind.

    line 62
  2. Very specific:

    All secrets go in .env (gitignored) — never hardcode API keys, connection strings, or tokens

    line 73

≈ “Common” is an estimate: at least 1 in 5 of the 3,669 Copilot instructions files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
copilot-instructions.md

Copilot Instructions — Refund Agent (A365 + 3IQs)

Scope

This sample is part of the microsoft/iq-samples repo. Only read and modify files within this folder (refund-agent-a365/). Do not touch other samples or root-level governance files (LICENSE, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md).

Project Identity

This is a Python agent that wraps an Microsoft Foundry agent (with Fabric Data Agent + Work IQ tools) and publishes it to Microsoft Teams / M365 Copilot via the Microsoft Agent 365 (A365) SDK. The Foundry agent handles all intelligence; this project is the A365 hosting wrapper that adds Teams messaging, notifications, observability, and user identity passthrough (OBO).

Tech Stack

ComponentTechnology
Agent hostPython 3.11+, A365 SDK (microsoft-agents-* packages), aiohttp
Dashboard backendPython, FastAPI
Dashboard frontendReact, TypeScript, Vite
DeploymentAzure App Service (Linux), Microsoft Foundry

Key Files

FilePurpose
agent/agent.pyCore agent logic — connects to Foundry agent via OBO token, streams responses
agent/agent_interface.pyA365 activity handler — receives Teams messages, routes to agent.py
agent/host_agent_server.pyaiohttp server entry point for A365
agent/start_with_generic_host.pyGeneric host launcher (used as Azure startup command)
agent/token_cache.pyOBO token acquisition and caching
agent/.env.templateEnvironment variable template — copy to .env and fill in values
agent/a365.config.example.jsonA365 CLI config template
agent-instructions.mdFoundry agent system prompt (paste into Microsoft Foundry UI — this is NOT code)
dashboard/Full-stack demo dashboard (FastAPI backend + React frontend)
azure.yamlAzure Developer CLI deployment descriptor
scripts/setup_foundry_agent.pyProgrammatic Foundry agent creation with IQ tools (uses azure-ai-agents SDK)
scripts/requirements.txtDependencies for the setup script (separate from agent deps)

Setup Script

scripts/setup_foundry_agent.py programmatically creates the Foundry agent with SDK-supported IQ tools (FileSearchTool for Foundry IQ, FabricTool for Fabric IQ). Work IQ has no SDK class and must be configured in the portal. The script depends on scripts/requirements.txt (separate from the agent's requirements). Auth uses az login (AzureCliCredential), not the API key.

What NOT to Touch

  • agent-instructions.md contains the Foundry agent's system prompt. It is documentation for the AI Foundry portal, not executable code. Do not refactor or "fix" it.
  • .env files are gitignored. Never create or commit them. Use .env.template for documenting required variables.
  • Do not add or remove A365 SDK packages without understanding the A365 hosting contract.

Dependencies

# Agent
cd agent && pip install -r requirements.txt

# Dashboard backend
cd dashboard/backend && pip install -r requirements.txt

# Dashboard frontend
cd dashboard/frontend && npm install

Troubleshooting & Known Errors

IMPORTANT: When encountering any errors during setup, deployment, or runtime, always check TROUBLESHOOTING.md first before debugging blind. It contains solutions for all known issues including:

  • RBAC/permission errors (401, 403)
  • OBO token failures (ARA OBO, BadRequest)
  • Foundry agent errors (404, model mismatch)
  • Work IQ issues (email search, tenant denied, 502 on email channel)
  • Fabric Data Agent failures (tool_user_error, prerequisites)
  • Deployment issues (timeout, quota, WAM auth)
  • Dashboard errors (httpx, MSAL redirect, managed identity)

Security

  • All secrets go in .env (gitignored) — never hardcode API keys, connection strings, or tokens
  • OBO token flow is security-critical — changes to token_cache.py or auth logic need careful review
  • The A365 config contains tenant and app IDs — use the example file, never commit real values

Download now (ZIP)

  • Where files are headingNew Copilot instructions files have more rules about branches and pull requests, and fewer about code style.

    Of the Copilot instructions files we read, the 2,297 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository2 other files it gives its agents.

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free