@ivannxbt/ai-config 0.1.0

package/.agents/skills/microsoft-foundry/foundry-agent/create/create.md

@@ -0,0 +1,239 @@
+# Create Hosted Agent Application
+
+Create new hosted agent applications for Microsoft Foundry, or convert existing agent projects to be Foundry-compatible using the hosting adapter.
+
+## Quick Reference
+
+| Property | Value |
+|----------|-------|
+| **Samples Repo** | `microsoft-foundry/foundry-samples` |
+| **Python Samples** | `samples/python/hosted-agents/{framework}/` |
+| **C# Samples** | `samples/csharp/hosted-agents/{framework}/` |
+| **Hosted Agents Docs** | https://learn.microsoft.com/azure/ai-foundry/agents/concepts/hosted-agents |
+| **Best For** | Creating new or converting existing agent projects for Foundry |
+
+## When to Use This Skill
+
+- Create a new hosted agent application from scratch (greenfield)
+- Start from an official sample and customize it
+- Convert an existing agent project to be Foundry-compatible (brownfield)
+- Help user choose a framework or sample for their agent
+
+## Workflow
+
+### Step 1: Determine Scenario
+
+Check the user's workspace for existing agent project indicators:
+
+- **No agent-related code found** → **Greenfield**. Proceed to Greenfield Workflow (Step 2).
+- **Existing agent code present** → **Brownfield**. Proceed to Brownfield Workflow.
+
+### Step 2: Gather Requirements (Greenfield)
+
+If the user hasn't already specified, use `ask_user` to collect:
+
+**Framework:**
+
+| Framework | Python Path | C# Path |
+|-----------|------------|---------|
+| Microsoft Agent Framework (default) | `agent-framework` | `AgentFramework` |
+| LangGraph | `langgraph` | ❌ Python only |
+| Custom | `custom` | `AgentWithCustomFramework` |
+
+**Language:** Python (default) or C#.
+
+> ⚠️ **Warning:** LangGraph is Python-only. For C# + LangGraph, suggest Agent Framework or Custom instead.
+
+If user has no specific preference, suggest Microsoft Agent Framework + Python as defaults.
+
+### Step 3: Browse and Select Sample
+
+List available samples using the GitHub API:
+
+```
+GET https://api.github.com/repos/microsoft-foundry/foundry-samples/contents/samples/{language}/hosted-agents/{framework}
+```
+
+If the user has specified any information on what they want their agent to do, just choose the most relevant or most simple sample to start with. Only if user has not given any preferences, present the sample directories to the user and help them choose based on their requirements (e.g., RAG, tools, multi-agent workflows, HITL).
+
+### Step 4: Download Sample Files
+
+Download only the selected sample directory — do NOT clone the entire repo. Preserve the directory structure by creating subdirectories as needed.
+
+**Using `gh` CLI (preferred if available):**
+```bash
+gh api repos/microsoft-foundry/foundry-samples/contents/samples/{language}/hosted-agents/{framework}/{sample} \
+  --jq '.[] | select(.type=="file") | .download_url' | while read url; do
+  filepath="${url##*/samples/{language}/hosted-agents/{framework}/{sample}/}"
+  mkdir -p "$(dirname "$filepath")"
+  curl -sL "$url" -o "$filepath"
+done
+```
+
+**Using curl (fallback):**
+```bash
+curl -s "https://api.github.com/repos/microsoft-foundry/foundry-samples/contents/samples/{language}/hosted-agents/{framework}/{sample}" | \
+  jq -r '.[] | select(.type=="file") | .path + "\t" + .download_url' | while IFS=$'\t' read path url; do
+    relpath="${path#samples/{language}/hosted-agents/{framework}/{sample}/}"
+    mkdir -p "$(dirname "$relpath")"
+    curl -sL "$url" -o "$relpath"
+  done
+```
+
+For nested directories, recursively fetch the GitHub contents API for entries where `type == "dir"` and repeat the download for each.
+
+### Step 5: Customize and Implement
+
+1. Read the sample's README.md to understand its structure
+2. Read the sample code to understand patterns and dependencies used
+3. If using Agent Framework, follow the best practices in [references/agentframework.md](references/agentframework.md)
+4. Implement the user's specific requirements on top of the sample
+5. Update configuration (`.env`, dependency files) as needed.
+6. Ensure the project is in a runnable state
+
+### Step 6: Verify Startup
+
+1. Install dependencies (use virtual environment for Python)
+2. Ask user to provide values for .env variables if placeholders were used using `ask_user` tool.
+3. Run the main entrypoint
+4. Fix startup errors and retry if needed
+5. Send a test request to the agent. The agent will support OpenAI Responses schema.
+6. Fix any errors from the test request and retry until it succeeds
+7. Once startup and test request succeed, stop the server to prevent resource usage
+
+**Guardrails:**
+- ✅ Perform real run to catch startup errors
+- ✅ Cleanup after verification (stop server)
+- ✅ Ignore auth/connection/timeout errors (expected without Azure config)
+- ❌ Don't wait for user input or create test scripts
+
+## Brownfield Workflow: Convert Existing Agent to Hosted Agent
+
+Use this workflow when the user has an existing agent project that needs to be made compatible with Foundry hosted agent deployment. The key requirement is wrapping the agent with the appropriate **hosting adapter** package, which converts any agent into an HTTP service compatible with the Foundry Responses API.
+
+### Step B1: Analyze Existing Project
+
+Scan the project to determine:
+
+1. **Language** — Python (look for `requirements.txt`, `pyproject.toml`, `*.py`) or C# (look for `*.csproj`, `*.cs`)
+2. **Framework** — Identify which agent framework is in use:
+
+| Indicator | Framework |
+|-----------|-----------|
+| Imports from `agent_framework` or `Microsoft.Agents.AI` | Microsoft Agent Framework |
+| Imports from `langgraph`, `langchain` | LangGraph |
+| No recognized framework imports, or other frameworks (e.g., Semantic Kernel, AutoGen) | Custom |
+
+3. **Entry point** — Identify the main script/entrypoint that creates and runs the agent
+4. **Agent object** — Identify the agent instance that needs to be wrapped (e.g., a `BaseAgent` subclass, a compiled `StateGraph`, or an existing server/app)
+
+### Step B2: Add Hosting Adapter Dependency
+
+Add the correct adapter package based on framework and language. Get the latest version from the package registry — do not hardcode versions.
+
+**Python adapter packages:**
+
+| Framework | Package |
+|-----------|---------|
+| Microsoft Agent Framework | `azure-ai-agentserver-agentframework` |
+| LangGraph | `azure-ai-agentserver-langgraph` |
+| Custom | `azure-ai-agentserver-core` |
+
+**.NET adapter packages:**
+
+| Framework | Package |
+|-----------|---------|
+| Microsoft Agent Framework | `Azure.AI.AgentServer.AgentFramework` |
+| Custom | `Azure.AI.AgentServer.Core` |
+
+Add the package to the project's dependency file (`requirements.txt`, `pyproject.toml`, or `.csproj`). For Python, also add `python-dotenv` if not present.
+
+### Step B3: Wrap Agent with Hosting Adapter
+
+Modify the project's main entrypoint to wrap the existing agent with the adapter. The approach differs by framework:
+
+**Microsoft Agent Framework (Python):**
+- Import `from_agent_framework` from the adapter package
+- Pass the agent instance (a `BaseAgent` subclass) to the adapter
+- Call `.run()` on the adapter as the default entrypoint
+- The agent must implement both `run()` and `run_stream()` methods
+
+**LangGraph (Python):**
+- Import `from_langgraph` from the adapter package
+- Pass the compiled `StateGraph` to the adapter
+- Call `.run()` on the adapter as the default entrypoint
+
+**Custom code (Python):**
+- Import `FoundryCBAgent` from the core adapter package
+- Create a class that extends `FoundryCBAgent`
+- Implement the `agent_run()` method which receives an `AgentRunContext` and returns either an `OpenAIResponse` (non-streaming) or `AsyncGenerator[ResponseStreamEvent]` (streaming)
+- The agent must handle the Foundry request/response protocol manually — refer to the [custom sample](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/custom) for the exact interface
+- Instantiate and call `.run()` as the default entrypoint
+
+**Custom code (C#):**
+- Use `AgentServerApplication.RunAsync()` with dependency injection to register an `IAgentInvocation` implementation
+- Refer to the [C# custom sample](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/csharp/hosted-agents/AgentWithCustomFramework) for the exact interface
+
+> ⚠️ **Warning:** The adapter MUST be the default entrypoint (no flags required to start). This is required for both local debugging and containerized deployment.
+
+### Step B4: Configure Environment
+
+1. Create or update a `.env` file with required environment variables (project endpoint, model deployment name, etc.)
+2. For Python: ensure the code uses `load_dotenv()` so Foundry-injected environment variables is available at runtime.
+3. If the project uses Azure credentials: ensure Python uses `azure.identity.aio.DefaultAzureCredential` (async version) for **local development**, not `azure.identity.DefaultAzureCredential`. In production, use `ManagedIdentityCredential`. See [auth-best-practices.md](../../references/auth-best-practices.md)
+
+### Step B5: Create agent.yaml
+
+Create an `agent.yaml` file in the project root. This file defines the agent's metadata and deployment configuration for Foundry. Required fields:
+
+- `name` — Unique identifier (alphanumeric + hyphens, max 63 chars)
+- `description` — What the agent does
+- `template.kind` — Must be `hosted`
+- `template.protocols` — Must include `responses` protocol v1
+- `template.environment_variables` — List all environment variables the agent needs at runtime
+
+Refer to any sample's `agent.yaml` in the [foundry-samples repo](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents) for the exact schema.
+
+### Step B6: Create Dockerfile
+
+Create a `Dockerfile` if one doesn't exist. Requirements:
+
+- Base image appropriate for the language (e.g., `python:3.12-slim` for Python, `mcr.microsoft.com/dotnet/sdk` for C#)
+- Copy source code into the container
+- Install dependencies
+- Expose port **8088** (the adapter's default port)
+- Set the main entrypoint as the CMD
+
+> ⚠️ **Warning:** When building, MUST use `--platform linux/amd64`. Hosted agents run on Linux AMD64 infrastructure. Images built for other architectures (e.g., ARM64 on Apple Silicon) will fail.
+
+Refer to any sample's `Dockerfile` in the [foundry-samples repo](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents) for the exact pattern.
+
+### Step B7: Test Locally
+
+1. Install dependencies (use virtual environment for Python)
+2. Run the main entrypoint — the adapter should start an HTTP server on `localhost:8088`
+3. Send a test request: `POST http://localhost:8088/responses` with body `{"input": "hello"}`
+4. Verify the response follows the OpenAI Responses API format
+5. Fix any errors and retry until the test request succeeds
+6. Stop the server
+
+> 💡 **Tip:** If auth/connection errors occur for Azure services, that's expected without real Azure credentials configured. The key validation is that the HTTP server starts and accepts requests.
+
+## Common Guidelines
+
+IMPORTANT: YOU MUST FOLLOW THESE.
+
+Apply these to both greenfield and brownfield projects:
+
+1. **Logging** — Implement proper logging using the language's standard logging framework (Python `logging` module, .NET `ILogger`). Hosted agents stream container stdout/stderr logs to Foundry, so all log output is visible via the troubleshoot workflow. Use structured log levels (INFO, WARNING, ERROR) and include context like request IDs and agent names.
+
+2. **Framework-specific best practices** — When using Agent Framework, read the [Agent Framework best practices](references/agentframework.md) for hosting adapter setup, credential patterns, and debugging guidance.
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| GitHub API rate limit | Too many requests | Authenticate with `gh auth login` |
+| `gh` not available | CLI not installed | Use curl REST API fallback |
+| Sample not found | Path changed in repo | List parent directory to discover current samples |
+| Dependency install fails | Version conflicts | Use versions from sample's own dependency file |

package/.agents/skills/microsoft-foundry/foundry-agent/create/references/agent-tools.md

@@ -0,0 +1,45 @@
+# Agent Tools — Simple Tools
+
+Add tools to agents to extend capabilities. This file covers tools that work without external connections. For tools requiring connections/RBAC setup, see:
+- [Web Search tool](tool-web-search.md) — real-time public web search with citations (default for web search)
+- [Bing Grounding tool](tool-bing-grounding.md) — web search via dedicated Bing resource (only when explicitly requested)
+- [Azure AI Search tool](tool-azure-ai-search.md) — private data grounding with vector search
+- [MCP tool](tool-mcp.md) — remote Model Context Protocol servers
+
+## Code Interpreter
+
+Enables agents to write and run Python in a sandboxed environment. Supports data analysis, chart generation, and file processing. Has [additional charges](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/) beyond token-based fees.
+
+> Sessions: 1-hour active / 30-min idle timeout. Each conversation = separate billable session.
+
+For code samples, see: [Code Interpreter tool documentation](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/code-interpreter?view=foundry)
+
+## Function Calling
+
+Define custom functions the agent can invoke. Your app executes the function and returns results. Runs expire 10 minutes after creation — return tool outputs promptly.
+
+> **Security:** Treat tool arguments as untrusted input. Don't pass secrets in tool output. Use `strict=True` for schema validation.
+
+For code samples, see: [Function Calling tool documentation](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/function-calling?view=foundry)
+
+## Tool Summary
+
+| Tool | Connection? | Reference |
+|------|-------------|-----------|
+| `CodeInterpreterTool` | No | This file |
+| `FileSearchTool` | No (vector store required) | [tool-file-search.md](tool-file-search.md) |
+| `FunctionTool` | No | This file |
+| `WebSearchPreviewTool` | No | [tool-web-search.md](tool-web-search.md) |
+| `BingGroundingAgentTool` | Yes (Bing) | [tool-bing-grounding.md](tool-bing-grounding.md) |
+| `AzureAISearchAgentTool` | Yes (Search) | [tool-azure-ai-search.md](tool-azure-ai-search.md) |
+| `MCPTool` | Optional | [tool-mcp.md](tool-mcp.md) |
+
+> ⚠️ **Default for web search:** Use `WebSearchPreviewTool` unless the user explicitly requests Bing Grounding or Bing Custom Search.
+
+> Combine multiple tools on one agent. The model decides which to invoke.
+
+## References
+
+- [Tool Catalog](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/tool-catalog?view=foundry)
+- [Code Interpreter](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/code-interpreter?view=foundry)
+- [Function Calling](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/function-calling?view=foundry)

package/.agents/skills/microsoft-foundry/foundry-agent/create/references/agentframework.md

@@ -0,0 +1,92 @@
+# Microsoft Agent Framework — Best Practices for Hosted Agents
+
+Best practices when building hosted agents with Microsoft Agent Framework for deployment to Foundry Agent Service.
+
+## Official Resources
+
+| Resource | URL |
+|----------|-----|
+| **GitHub Repo** | https://github.com/microsoft/agent-framework |
+| **MS Learn Overview** | https://learn.microsoft.com/agent-framework/overview/agent-framework-overview |
+| **Quick Start** | https://learn.microsoft.com/agent-framework/tutorials/quick-start |
+| **User Guide** | https://learn.microsoft.com/agent-framework/user-guide/overview |
+| **Hosted Agents Concepts** | https://learn.microsoft.com/azure/ai-foundry/agents/concepts/hosted-agents |
+| **Python Samples (MAF repo)** | https://github.com/microsoft/agent-framework/tree/main/python/samples |
+| **.NET Samples (MAF repo)** | https://github.com/microsoft/agent-framework/tree/main/dotnet/samples |
+| **PyPI** | https://pypi.org/project/agent-framework/ |
+| **NuGet** | https://www.nuget.org/profiles/MicrosoftAgentFramework/ |
+
+## Installation
+
+**Python:** `pip install agent-framework --pre` (installs all sub-packages)
+
+**.NET:** `dotnet add package Microsoft.Agents.AI`
+
+> ⚠️ **Warning:** Always pin specific pre-release versions. Use `--pre` to get the latest. Check the [PyPI page](https://pypi.org/project/agent-framework/) or [NuGet profile](https://www.nuget.org/profiles/MicrosoftAgentFramework/) for current stable versions.
+
+## Hosting Adapter
+
+Hosted agents must expose an HTTP server using the hosting adapter. This enables local testing and Foundry deployment with the same code.
+
+**Python adapter packages:** `azure-ai-agentserver-core`, `azure-ai-agentserver-agentframework`
+
+**.NET adapter packages:** `Azure.AI.AgentServer.Core`, `Azure.AI.AgentServer.AgentFramework`
+
+The adapter handles protocol translation between Foundry request/response formats and your framework's native data structures, including conversation management, message serialization, and streaming.
+
+> 💡 **Tip:** Make HTTP server mode the default entrypoint (no flags needed). This simplifies both local debugging and containerized deployment.
+
+## Key Patterns
+
+### Python: Async Credentials
+
+For **local development**, use `DefaultAzureCredential` from `azure.identity.aio` (not `azure.identity`) — `AzureAIClient` requires async credentials. In production, use `ManagedIdentityCredential` from `azure.identity.aio`. See [auth-best-practices.md](../../../references/auth-best-practices.md).
+
+### Python: Environment Variables
+
+Always use `load_dotenv(override=False)` so environment variables set by Foundry at runtime take precedence over local `.env` values.
+
+Required `.env` variables:
+- `FOUNDRY_PROJECT_ENDPOINT` — project endpoint URL
+- `FOUNDRY_MODEL_DEPLOYMENT_NAME` — model deployment name
+
+### Authentication
+
+If explicitly asked to use API key instead of managed identity, then use AzureOpenAIResponsesClient and pass in api_key parameter to it.
+
+### Agent Naming Rules
+
+Agent names must: start/end with alphanumeric characters, may contain hyphens in the middle, max 63 characters. Examples: `MyAgent`, `agent-1`. Invalid: `-agent`, `agent-`, `sample_agent`.
+
+### Python: Virtual Environment
+
+Always use a virtual environment. Never use bare `python` or `pip` — use venv-activated versions or full paths (e.g., `.venv/bin/pip`).
+
+## Workflow Patterns
+
+Agent Framework supports single-agent and multi-agent workflow patterns using graph-based orchestration:
+
+- **Single Agent** — Basic agent with tools, RAG, or MCP integration
+- **Multi-Agent Workflow** — Graph-based orchestration connecting multiple agents and deterministic functions
+- **Advanced Patterns** — Reflection, switch-case, fan-out/fan-in, loop, human-in-the-loop
+
+For workflow samples and advanced patterns, search the [Agent Framework GitHub repo](https://github.com/microsoft/agent-framework).
+
+## Debugging
+
+Use [AI Toolkit for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio) with the `agentdev` CLI tool for interactive debugging:
+
+1. Install `debugpy` for VS Code Python Debugger support
+2. Install `agent-dev-cli` (pre-release) for the `agentdev` command
+3. Key debug tasks: `agentdev run <entrypoint>.py --port 8087` starts the agent HTTP server, `debugpy --listen 127.0.0.1:5679` attaches the debugger, and the `ai-mlstudio.openTestTool` VS Code command opens the Agent Inspector UI
+
+For VS Code `launch.json` and `tasks.json` configuration templates, see [AI Toolkit Agent Inspector — Configure debugging manually](https://github.com/microsoft/vscode-ai-toolkit/blob/main/doc/agent-test-tool.md#configure-debugging-manually).
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `ModuleNotFoundError` | Missing SDK | `pip install agent-framework --pre` in venv |
+| Async credential error | Wrong import | Use `azure.identity.aio.DefaultAzureCredential` (local dev) or `azure.identity.aio.ManagedIdentityCredential` (production) |
+| Agent name validation error | Invalid characters | Use alphanumeric + hyphens, start/end alphanumeric, max 63 chars |
+| Hosting adapter not found | Missing package | Install `azure-ai-agentserver-agentframework` |

package/.agents/skills/microsoft-foundry/foundry-agent/create/references/sdk-operations.md

@@ -0,0 +1,47 @@
+# SDK Operations for Foundry Agent Service
+
+Use the Foundry MCP tools for agent CRUD operations. When MCP tools are unavailable, use the `azure-ai-projects` Python SDK or REST API.
+
+## Agent Operations via MCP
+
+| Operation | MCP Tool | Description |
+|-----------|----------|-------------|
+| Create/Update agent | `agent_update` | Create a new agent or update an existing one (creates new version) |
+| List/Get agents | `agent_get` | List all agents, or get a specific agent by name |
+| Delete agent | `agent_delete` | Delete an agent |
+| Invoke agent | `agent_invoke` | Send a message to an agent and get a response |
+| Get schema | `agent_definition_schema_get` | Get the full JSON schema for agent definitions |
+
+## SDK Agent Operations
+
+When MCP tools are unavailable, use the `azure-ai-projects` Python SDK (`pip install azure-ai-projects --pre`):
+
+```python
+from azure.ai.projects import AIProjectClient
+from azure.identity import DefaultAzureCredential
+
+endpoint = "https://<resource>.services.ai.azure.com/api/projects/<project>"
+client = AIProjectClient(endpoint=endpoint, credential=DefaultAzureCredential())
+```
+
+| Operation | SDK Method |
+|-----------|------------|
+| Create | `client.agents.create_version(agent_name, definition)` |
+| List | `client.agents.list()` |
+| Get | `client.agents.get(agent_name)` |
+| Update | `client.agents.create_version(agent_name, definition)` (creates new version) |
+| Delete | `client.agents.delete(agent_name)` |
+| Chat | `client.get_openai_client().responses.create(model=<deployment>, input=<text>, extra_body={"agent": {"name": agent_name, "type": "agent_reference"}})` |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PROJECT_ENDPOINT` | Foundry project endpoint (`https://<resource>.services.ai.azure.com/api/projects/<project>`) |
+| `MODEL_DEPLOYMENT_NAME` | Deployed model name (e.g., `gpt-4.1-mini`) |
+
+## References
+
+- [Agent quickstart](https://learn.microsoft.com/azure/ai-foundry/agents/quickstart?view=foundry)
+- [Create agents](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/create-agent?view=foundry)
+- [Tool Catalog](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/tool-catalog?view=foundry)

package/.agents/skills/microsoft-foundry/foundry-agent/create/references/tool-azure-ai-search.md

@@ -0,0 +1,69 @@
+# Azure AI Search Tool
+
+Ground agent responses with data from an Azure AI Search vector index. Requires a project connection and proper RBAC setup.
+
+## Prerequisites
+
+- Azure AI Search index with vector search configured:
+  - One or more `Edm.String` fields (searchable + retrievable)
+  - One or more `Collection(Edm.Single)` vector fields (searchable)
+  - At least one retrievable text field with content for citations
+  - A retrievable field with source URL for citation links
+- A [project connection](../../../project/connections.md) between your Foundry project and search service
+- `azure-ai-projects` package (`pip install azure-ai-projects --pre`)
+
+## Required RBAC Roles
+
+For **keyless authentication** (recommended), assign these roles to the **Foundry project's managed identity** on the Azure AI Search resource:
+
+| Role | Scope | Purpose |
+|------|-------|---------|
+| **Search Index Data Contributor** | AI Search resource | Read/write index data |
+| **Search Service Contributor** | AI Search resource | Manage search service config |
+
+> **If RBAC assignment fails:** Ask the user to manually assign roles in Azure portal → AI Search resource → Access control (IAM). They need Owner or User Access Administrator on the search resource.
+
+## Connection Setup
+
+A project connection between your Foundry project and the Azure AI Search resource is required. See [Project Connections](../../../project/connections.md) for connection management via Foundry MCP tools.
+
+## Query Types
+
+| Value | Description |
+|-------|-------------|
+| `SIMPLE` | Keyword search |
+| `VECTOR` | Vector similarity only |
+| `SEMANTIC` | Semantic ranking |
+| `VECTOR_SIMPLE_HYBRID` | Vector + keyword |
+| `VECTOR_SEMANTIC_HYBRID` | Vector + keyword + semantic (default, recommended) |
+
+## Tool Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `project_connection_id` | Yes | Connection ID (resolve via `foundry_connections_get`) |
+| `index_name` | Yes | Search index name |
+| `top_k` | No | Number of results (default: 5) |
+| `query_type` | No | Search type (default: `vector_semantic_hybrid`) |
+| `filter` | No | OData filter applied to all queries |
+
+## Limitations
+
+- Only **one index per tool** instance. For multiple indexes, use connected agents each with their own index.
+- Search resource and Foundry agent must be in the **same tenant**.
+- Private AI Search resources require **standard agent deployment** with vNET injection.
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| 401/403 accessing index | Missing RBAC roles | Assign `Search Index Data Contributor` + `Search Service Contributor` to project managed identity |
+| Index not found | Name mismatch | Verify `AI_SEARCH_INDEX_NAME` matches exactly (case-sensitive) |
+| No citations in response | Instructions don't request them | Add citation instructions to agent prompt |
+| Wrong connection endpoint | Connection points to different search resource | Re-create connection with correct endpoint |
+
+## References
+
+- [Azure AI Search tool documentation](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/azure-ai-search?view=foundry)
+- [Tool Catalog](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/tool-catalog?view=foundry)
+- [Project Connections](../../../project/connections.md)

package/.agents/skills/microsoft-foundry/foundry-agent/create/references/tool-bing-grounding.md

@@ -0,0 +1,50 @@
+# Bing Grounding Tool
+
+Access real-time web information via Bing Search. Unlike the [Web Search tool](tool-web-search.md) (which works out of the box), Bing Grounding requires a dedicated Bing resource and a project connection.
+
+> ⚠️ **Warning:** Use the [Web Search tool](tool-web-search.md) as the default for web search. Only use Bing Grounding when the user **explicitly** requests Grounding with Bing Search or Grounding with Bing Custom Search.
+
+## When to Use
+
+- User explicitly asks for "Bing Grounding" or "Grounding with Bing Search"
+- User explicitly asks for "Bing Custom Search" or "Grounding with Bing Custom Search"
+- User needs to restrict web search to specific domains (Bing Custom Search)
+- User has an existing Bing Grounding resource they want to use
+
+## Prerequisites
+
+- A [Grounding with Bing Search resource](https://portal.azure.com/#create/Microsoft.BingGroundingSearch) in Azure portal
+- `Contributor` or `Owner` role at subscription/RG level to create Bing resource and get keys
+- `Azure AI Project Manager` role on the project to create a connection
+- A project connection configured with the Bing resource key — see [connections](../../../project/connections.md)
+
+## Setup
+
+1. Register the Bing provider: `az provider register --namespace 'Microsoft.Bing'`
+2. Create a Grounding with Bing Search resource in the Azure portal
+3. Create a project connection with the Bing resource key — see [connections](../../../project/connections.md)
+4. Set `BING_PROJECT_CONNECTION_NAME` environment variable
+
+## Important Disclosures
+
+- Bing data flows **outside Azure compliance boundary**
+- Review [Grounding with Bing terms of use](https://www.microsoft.com/bing/apis/grounding-legal-enterprise)
+- Not supported with VPN/Private Endpoints
+- Usage incurs costs — see [pricing](https://www.microsoft.com/bing/apis/grounding-pricing)
+
+## Troubleshooting
+
+| Issue | Cause | Resolution |
+|-------|-------|------------|
+| Connection not found | Name mismatch or wrong project | Use `foundry_connections_list` to find correct name |
+| Unauthorized creating connection | Missing Azure AI Project Manager role | Assign role on the Foundry project |
+| Bing resource creation fails | Provider not registered | Run `az provider register --namespace 'Microsoft.Bing'` |
+| No results returned | Connection misconfigured | Verify Bing resource key and connection setup |
+
+## References
+
+- [Bing Grounding tool documentation](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/bing-grounding?view=foundry)
+- [Tool Catalog](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/tool-catalog?view=foundry)
+- [Grounding with Bing Terms](https://www.microsoft.com/bing/apis/grounding-legal-enterprise)
+- [Connections Guide](../../../project/connections.md)
+- [Web Search Tool (default)](tool-web-search.md)

package/.agents/skills/microsoft-foundry/foundry-agent/create/references/tool-file-search.md

@@ -0,0 +1,60 @@
+# File Search Tool
+
+Enables agents to search through uploaded files using semantic and keyword search from vector stores. Supports a wide range of file formats including PDF, Markdown, Word, and more.
+
+> ⚠️ **Important:** Before creating an agent with file search, you **must** read the official documentation linked in the References section to understand prerequisites, supported file types, and vector store setup.
+
+## Prerequisites
+
+- A [basic or standard agent environment](https://learn.microsoft.com/azure/ai-foundry/agents/environment-setup)
+- A **vector store** must be created before the agent — the `file_search` tool requires `vector_store_ids`
+- Files must be uploaded to the vector store before the agent can search them
+
+## Key Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **Vector Store** | A container that indexes uploaded files for semantic search. Must be created first. |
+| **vector_store_ids** | Required parameter on the `file_search` tool — references the vector store(s) to search. |
+| **File upload** | Files are uploaded to the project, then attached to a vector store for indexing. |
+
+## Setup Workflow
+
+```
+1. Create a vector store (REST API: POST /vector_stores)
+   │
+   ▼
+2. (Optional) Upload files and attach to vector store
+   │
+   ▼
+3. Create agent with file_search tool referencing the vector_store_ids
+   │
+   ▼
+4. Agent can now search files in the vector store
+```
+
+> ⚠️ **Warning:** Creating an agent with `file_search` without providing `vector_store_ids` will fail with a `400 BadRequest` error: `required: Required properties ["vector_store_ids"] are not present`.
+
+## REST API Notes
+
+When creating vector stores via `az rest`:
+
+| Parameter | Value |
+|-----------|-------|
+| **Endpoint** | `https://<resource>.services.ai.azure.com/api/projects/<project>/vector_stores` |
+| **API version** | `v1` |
+| **Auth resource** | `https://ai.azure.com` |
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `vector_store_ids` not present | Agent created without vector store | Create a vector store first, then pass its ID |
+| 401 Unauthorized | Wrong auth resource for REST API | Use `--resource "https://ai.azure.com"` with `az rest` |
+| Bad API version | Using ARM-style API version | Use `api-version=v1` for the data-plane vector store API |
+| No search results | Vector store is empty | Upload files to the vector store before querying |
+
+## References
+
+- [File Search tool documentation](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/file-search?view=foundry&pivots=python)
+- [Tool Catalog](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/tool-catalog?view=foundry)