@ivannxbt/ai-config 0.1.0

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

@@ -0,0 +1,66 @@
+# MCP Tool (Model Context Protocol)
+
+Connect agents to remote MCP servers to extend capabilities with external tools and data sources. MCP is an open standard for LLM tool integration.
+
+## Prerequisites
+
+- A remote MCP server endpoint (e.g., `https://api.githubcopilot.com/mcp`)
+- For authenticated servers: a [project connection](../../../project/connections.md) storing credentials
+- RBAC: **Contributor** or **Owner** role on the Foundry project
+
+## Authenticated Server Connections
+
+For authenticated MCP servers, create an `api_key` project connection to store credentials. Unauthenticated servers (public endpoints) don't need a connection — omit `project_connection_id`.
+
+See [Project Connections](../../../project/connections.md) for connection management via Foundry MCP tools.
+
+## MCPTool Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `server_label` | Yes | Unique label for this MCP server within the agent |
+| `server_url` | Yes | Remote MCP server endpoint URL |
+| `require_approval` | No | `"always"` (default), `"never"`, or `{"never": ["tool1"]}` / `{"always": ["tool1"]}` |
+| `allowed_tools` | No | List of specific tools to enable (default: all) |
+| `project_connection_id` | No | Connection ID for authenticated servers |
+
+## Approval Workflow
+
+1. Agent sends request → MCP server returns tool calls
+2. Response contains `mcp_approval_request` items
+3. Your code reviews tool name + arguments
+4. Submit `McpApprovalResponse` with `approve=True/False`
+5. Agent completes work using approved tool results
+
+> **Best practice:** Always use `require_approval="always"` unless you fully trust the MCP server. Use `allowed_tools` to restrict which tools the agent can access.
+
+## Hosting Local MCP Servers
+
+Agent Service only accepts **remote** MCP endpoints. To use a local server, deploy it to:
+
+| Platform | Transport | Notes |
+|----------|-----------|-------|
+| [Azure Container Apps](https://github.com/Azure-Samples/mcp-container-ts) | HTTP POST/GET | Any language, container rebuild needed |
+| [Azure Functions](https://github.com/Azure-Samples/mcp-sdk-functions-hosting-python) | HTTP streamable | Python/Node/.NET/Java, key-based auth |
+
+## Known Limitations
+
+- **100-second timeout** for non-streaming MCP tool calls
+- **Identity passthrough not supported in Teams** — agents published to Teams use project managed identity
+- **Network-secured Foundry** can't use private MCP servers in same vNET — only public endpoints
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Invalid tool schema` | `anyOf`/`allOf` in MCP server definition | Update MCP server schema to use simple types |
+| `Unauthorized` / `Forbidden` | Wrong credentials in connection | Verify connection credentials match server requirements |
+| Model never calls MCP tool | Misconfigured server_label/url | Check `server_label`, `server_url`, `allowed_tools` values |
+| Agent stalls after approval | Missing `previous_response_id` | Include `previous_response_id` in follow-up request |
+| Timeout | Server takes >100s | Optimize server-side logic or break into smaller operations |
+
+## References
+
+- [MCP tool documentation](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/mcp?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-memory.md

@@ -0,0 +1,109 @@
+# Agent Memory
+
+Managed long-term memory for Foundry agents. Enables agent continuity across sessions, devices, and workflows. Agents retain user preferences, conversation history, and deliver personalized experiences. Memory is stored in your project's owned storage.
+
+## Prerequisites
+
+- A [Foundry project](https://learn.microsoft.com/azure/ai-foundry/how-to/create-projects) with authorization configured
+- A **chat model deployment** (e.g., `gpt-5.2`)
+- An **embedding model deployment** (e.g., `text-embedding-3-small`) — see [Check Embedding Model](#check-embedding-model) below
+- Python packages: `pip install azure-ai-projects azure-identity`
+
+### Check Embedding Model
+
+An embedding model is **required** before enabling memory. Check if one is already deployed:
+
+Use `foundry_models_list` MCP tool to list all deployments and look for an embedding model (e.g., `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`).
+
+| Result | Action |
+|--------|--------|
+| ✅ Embedding model found | Note the deployment name and proceed |
+| ❌ No embedding model | Deploy one before enabling memory — see below |
+
+### Deploy Embedding Model
+
+If no embedding model exists, use `foundry_models_deploy` MCP tool with:
+- `deploymentName`: `text-embedding-3-small` (or preferred name)
+- `modelName`: `text-embedding-3-small`
+- `modelFormat`: `OpenAI`
+
+## Authorization and Permissions
+
+| Role | Scope | Purpose |
+|------|-------|---------|
+| **Azure AI User** | AI Services resource | Assigned to project managed identity |
+| **System-assigned managed identity** | Project | Must be enabled on the project |
+
+**Setup steps:**
+1. In Azure portal → project → **Resource Management** → **Identity** → enable system-assigned managed identity
+2. On the AI Services resource → **Access control (IAM)** → assign **Azure AI User** to the project managed identity
+
+## Workflow
+
+```
+User wants agent memory
+    │
+    ▼
+Step 1: Check for embedding model deployment
+    │  ├─ ✅ Found → Continue
+    │  └─ ❌ Not found → Deploy one (ask user)
+    │
+    ▼
+Step 2: Create memory store
+    │
+    ▼
+Step 3: Attach memory tool to agent
+    │
+    ▼
+Step 4: Test with conversation
+```
+
+## Key Concepts
+
+### Memory Store Options
+
+| Option | Description |
+|--------|-------------|
+| `chat_summary_enabled` | Summarize conversations for memory |
+| `user_profile_enabled` | Build and maintain user profile |
+| `user_profile_details` | Control what data gets stored (e.g., `"Avoid sensitive data such as age, financials, location, credentials"`) |
+
+> 💡 **Tip:** Use `user_profile_details` to control what the agent stores — e.g., `"flight carrier preference and dietary restrictions"` for a travel agent, or exclude sensitive data.
+
+### Scope
+
+The `scope` parameter partitions memory per user:
+
+| Scope Value | Behavior |
+|-------------|----------|
+| `{{$userId}}` | Auto-extracts TID+OID from auth token (recommended) |
+| `"user_123"` | Static identifier — you manage user mapping |
+
+### Memory Store Operations
+
+| Operation | Description |
+|-----------|-------------|
+| Create | Initialize a memory store with chat/embedding models and options |
+| List | List all memory stores in the project |
+| Update | Update memory store description or configuration |
+| Delete scope | Delete memories for a specific user scope |
+| Delete store | Delete entire memory store (irreversible — all scopes lost) |
+
+> ⚠️ **Warning:** Deleting a memory store removes all memories across all scopes. Agents with attached memory stores lose access to historical context.
+
+## Troubleshooting
+
+| Issue | Cause | Resolution |
+|-------|-------|------------|
+| Auth/authorization error | Identity or managed identity lacks required roles | Verify roles in Authorization section; refresh access token for REST |
+| Memories don't appear after conversation | Updates are debounced or still processing | Increase wait time or call update API with `update_delay=0` |
+| Memory search returns no results | Scope mismatch between update and search | Use same scope value for storing and retrieving memories |
+| Agent response ignores stored memory | Agent not configured with memory search tool | Confirm agent definition includes `MemorySearchTool` with correct store name |
+| No embedding model available | Embedding deployment missing | Deploy an embedding model — see Check Embedding Model section |
+
+## References
+
+- [Memory tool documentation](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/memory-usage?view=foundry)
+- [Memory Concepts](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/what-is-memory)
+- [Tool Catalog](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/tool-catalog?view=foundry)
+- [Python Samples](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/ai/azure-ai-projects/samples/memories)

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

@@ -0,0 +1,57 @@
+# Web Search Tool (Preview)
+
+Enables agents to retrieve and ground responses with real-time public web information before generating output. Returns up-to-date answers with inline URL citations. This is the **default tool for web search** — no external resource or connection setup required.
+
+> ⚠️ **Warning:** For Bing Grounding or Bing Custom Search (which require a separate Bing resource and project connection), see [tool-bing-grounding.md](tool-bing-grounding.md). Only use those when explicitly requested.
+
+## Important Disclosures
+
+- Web Search (preview) uses Grounding with Bing Search and Grounding with Bing Custom Search, which are [First Party Consumption Services](https://www.microsoft.com/licensing/terms/product/Glossary/EAEAS) governed by [Grounding with Bing terms of use](https://www.microsoft.com/bing/apis/grounding-legal-enterprise) and the [Microsoft Privacy Statement](https://go.microsoft.com/fwlink/?LinkId=521839&clcid=0x409).
+- The [Data Protection Addendum](https://aka.ms/dpa) **does not apply** to data sent to Grounding with Bing Search and Grounding with Bing Custom Search.
+- Data transfers occur **outside compliance and geographic boundaries**.
+- Usage incurs costs — see [pricing](https://www.microsoft.com/bing/apis/grounding-pricing).
+
+## Prerequisites
+
+- A [basic or standard agent environment](https://learn.microsoft.com/azure/ai-foundry/agents/environment-setup)
+- Azure credentials configured (e.g., `DefaultAzureCredential`)
+
+## Setup
+
+No external resource or project connection is required. The web search tool works out of the box when added to an agent definition.
+
+## Configuration Options
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `user_location` | Approximate location (country/region/city) for localized results | None |
+| `search_context_size` | Context window space for search: `low`, `medium`, `high` | `medium` |
+
+## Administrator Control
+
+Admins can enable or disable web search at the subscription level via Azure CLI. Requires Owner or Contributor access.
+
+- **Disable:** `az feature register --name OpenAI.BlockedTools.web_search --namespace Microsoft.CognitiveServices --subscription "<subscription-id>"`
+- **Enable:** `az feature unregister --name OpenAI.BlockedTools.web_search --namespace Microsoft.CognitiveServices --subscription "<subscription-id>"`
+
+## Security Considerations
+
+- Treat web search results as **untrusted input**. Validate before use in downstream systems.
+- Avoid sending secrets or sensitive data in prompts forwarded to external services.
+
+## Troubleshooting
+
+| Issue | Cause | Resolution |
+|-------|-------|------------|
+| No citations appear | Model didn't determine web search was needed | Update instructions to explicitly allow web search; ask queries requiring current info |
+| Requests fail after enabling | Web search disabled at subscription level | Ask admin to enable — see Administrator Control above |
+| Authentication errors (REST) | Bearer token missing, expired, or insufficient | Refresh token; confirm project/agent access |
+| Outdated results | Content not recently indexed by Bing | Refine query to request most recent info |
+| No results for specific topics | Query too narrow | Broaden query; niche topics may have limited coverage |
+| Rate limiting (429) | Too many requests | Implement exponential backoff; space out requests |
+
+## References
+
+- [Web Search tool documentation](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/web-search?view=foundry)
+- [Tool Catalog](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/tool-catalog?view=foundry)
+- [Bing Pricing](https://www.microsoft.com/bing/apis/grounding-pricing)

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

@@ -0,0 +1,319 @@
+# Foundry Agent Deploy
+
+Create and manage agent deployments in Azure AI Foundry. For hosted agents, this includes the full workflow from containerizing the project to starting the agent container.
+
+## Quick Reference
+
+| Property | Value |
+|----------|-------|
+| Agent types | Prompt (LLM-based), Hosted (ACA based), Hosted (vNext) |
+| MCP server | `foundry-mcp` |
+| Key MCP tools | `agent_update`, `agent_container_control`, `agent_container_status_get` |
+| CLI tools | `docker`, `az acr` (hosted agents only) |
+| Container protocols | `a2a`, `responses`, `mcp` |
+| Supported languages | .NET, Node.js, Python, Go, Java |
+
+## When to Use This Skill
+
+USE FOR: deploy agent to foundry, push agent to foundry, ship my agent, build and deploy container agent, deploy hosted agent, create hosted agent, deploy prompt agent, start agent container, stop agent container, ACR build, container image for agent, docker build for foundry, redeploy agent, update agent deployment, clone agent, delete agent, azd deploy hosted agent, azd ai agent, azd up for agent, deploy agent with azd.
+
+> ⚠️ **DO NOT manually run** `azd up`, `azd deploy`, `az acr build`, `docker build`, `agent_update`, or `agent_container_control` **without reading this skill first.** This skill orchestrates the full deployment pipeline: project scan → env var collection → Dockerfile generation → image build → agent creation → container startup → verification. Running CLI commands or calling MCP tools individually skips critical steps (env var confirmation, schema validation, status polling).
+
+## MCP Tools
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `agent_definition_schema_get` | Get JSON schema for agent definitions | `projectEndpoint` (required), `schemaType` (`prompt`, `hosted`, `tools`, `all`) |
+| `agent_update` | Create, update, or clone an agent | `projectEndpoint`, `agentName` (required); `agentDefinition` (JSON), `isCloneRequest`, `cloneTargetAgentName`, `modelName`, `creationOptions` (JSON with `description` and `metadata`) |
+| `agent_get` | List all agents or get a specific agent | `projectEndpoint` (required), `agentName` (optional) |
+| `agent_delete` | Delete an agent with container cleanup | `projectEndpoint`, `agentName` (required) |
+| `agent_container_control` | Start or stop a hosted agent container | `projectEndpoint`, `agentName`, `action` (`start`/`stop`) (required); `agentVersion`, `minReplicas`, `maxReplicas` |
+| `agent_container_status_get` | Check container running status | `projectEndpoint`, `agentName` (required); `agentVersion` |
+
+## Workflow: Hosted Agent Deployment
+There are two types of hosted agent - ACA based and vNext. There is only one change in the deployment flow for vNext which is indicated in the steps below. You must use vNext experience only when user explicitly asks you to deploy the agent to vNext (or v2, or v-next, or similar words). For all other cases, use the ACA based deployment flow.
+
+
+### Step 1: Detect and Scan Project
+
+Get the project path from the project context (see Common: Project Context Resolution). Detect the project type by checking for these files:
+
+| Project Type | Detection Files |
+|--------------|-----------------|
+| .NET | `*.csproj`, `*.fsproj` |
+| Node.js | `package.json` |
+| Python | `requirements.txt`, `pyproject.toml`, `setup.py` |
+| Go | `go.mod` |
+| Java (Maven) | `pom.xml` |
+| Java (Gradle) | `build.gradle` |
+
+Delegate an environment variable scan to a sub-agent. Provide the project path and project type. Search source files for these patterns:
+
+| Project Type | Patterns to Search |
+|--------------|--------------------|
+| .NET (`*.cs`) | `Environment.GetEnvironmentVariable("...")`, `configuration["..."]`, `configuration.GetValue<T>("...")` |
+| Node.js (`*.js`, `*.ts`, `*.mjs`) | `process.env.VAR_NAME`, `process.env["..."]` |
+| Python (`*.py`) | `os.environ["..."]`, `os.environ.get("...")`, `os.getenv("...")` |
+| Go (`*.go`) | `os.Getenv("...")`, `os.LookupEnv("...")` |
+| Java (`*.java`) | `System.getenv("...")`, `@Value("${...}")` |
+
+Classification: if followed by a throw/error → required; if followed by a fallback value → optional with default; otherwise → assume required, ask user.
+
+### Step 2: Collect and Confirm Environment Variables
+
+> ⚠️ **Warning:** Environment variables are included in the agent payload and are difficult to change after deployment.
+
+Use azd environment values from the project context to pre-fill discovered variables. Merge with any user-provided values. Present all variables to the user for confirmation with variable name, value, and source (`azd`, `project default`, or `user`). Mask sensitive values.
+
+Loop until the user confirms or cancels:
+- `yes` → Proceed
+- `VAR_NAME=new_value` → Update the value, show updated table, ask again
+- `cancel` → Abort deployment
+
+### Step 3: Generate Dockerfile and Build Image
+
+Delegate Dockerfile creation to a sub-agent. Guidelines:
+- Use official base image for the detected language and runtime version
+- Use multi-stage builds for compiled languages
+- Use Alpine or slim variants for smaller images
+- Always target `linux/amd64` platform
+- Expose the correct port (usually 8088)
+
+> 💡 **Tip:** Reference [Hosted Agents Foundry Samples](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents) for containerized agent examples.
+
+Also generate `docker-compose.yml` and `.env` files for local development.
+
+**IMPORTANT**: You MUST always generate image tag as current timestamp (e.g., `myagent:202401011230`) to ensure uniqueness and avoid conflicts with existing images in ACR. DO NOT use static tags like `latest` or `v1`.
+
+Collect ACR details from project context. Let the user choose the build method:
+
+**Cloud Build (ACR Tasks) (Recommended)** — no local Docker required:
+```bash
+az acr build --registry <acr-name> --image <repository>:<tag> --platform linux/amd64 --file Dockerfile .
+```
+
+**Local Docker Build:**
+```bash
+docker build --platform linux/amd64 -t <image>:<tag> -f Dockerfile .
+az acr login --name <acr-name>
+docker tag <image>:<tag> <acr-name>.azurecr.io/<repository>:<tag>
+docker push <acr-name>.azurecr.io/<repository>:<tag>
+```
+
+> 💡 **Tip:** Prefer Cloud Build if Docker is not available locally. On Windows with WSL, prefix Docker commands with `wsl -e` if `docker info` fails but `wsl -e docker info` succeeds.
+
+### Step 4: Collect Agent Configuration
+
+Use the project endpoint and ACR name from the project context. Ask the user only for values not already resolved:
+- **Agent name** — Unique name for the agent
+- **Model deployment** — Model deployment name (e.g., `gpt-4o`)
+
+### Step 5: Get Agent Definition Schema
+
+Use `agent_definition_schema_get` with `schemaType: hosted` to retrieve the current schema and validate required fields.
+
+### Step 6: Create the Agent
+
+> **VNext Experience:** You MUST pass `enableVnextExperience = true` in the `metadata` field of `creationOptions`. This is required for vNext deployments.
+
+Use `agent_update` with the agent definition:
+
+For ACA one:
+```json
+{
+  "kind": "hosted",
+  "image": "<acr-name>.azurecr.io/<repository>:<tag>",
+  "cpu": "<cpu-cores>",
+  "memory": "<memory>",
+  "container_protocol_versions": [
+    { "protocol": "<protocol>", "version": "<version>" }
+  ],
+  "environment_variables": { "<var>": "<value>" }
+}
+```
+
+For vNext one:
+```json
+{
+   "agentDefinition": {
+    "kind": "hosted",
+    "image": "<acr-name>.azurecr.io/<repository>:<tag>",
+    "cpu": "<cpu-cores>",
+    "memory": "<memory>",
+    "container_protocol_versions": [
+      { "protocol": "<protocol>", "version": "<version>" }
+    ],
+    "environment_variables": { "<var>": "<value>" }
+  },
+  "creationOptions": {
+    "metadata": {
+      "enableVnextExperience": "true"
+    }
+  }
+}
+```
+
+### Step 7: Start Agent Container
+
+Use `agent_container_control` with `action: start` to start the container.
+
+### Step 8: Verify Agent Status
+
+Delegate status polling to a sub-agent. Provide the project endpoint, agent name, and instruct it to use `agent_container_status_get` repeatedly until the status is `Running` or `Failed`.
+
+**Container status values:**
+- `Starting` — Container is initializing
+- `Running` — Container is active and ready ✅
+- `Stopped` — Container has been stopped
+- `Failed` — Container failed to start ❌
+
+### Step 9: Test the Agent
+
+Read and follow the [invoke skill](../invoke/invoke.md) to send a test message and verify the agent responds correctly. DO NOT SKIP reading the invoke skill — it contains important information about how to format messages for hosted agents for vNext experience.
+
+## Workflow: Prompt Agent Deployment
+
+### Step 1: Collect Agent Configuration
+
+Use the project endpoint from the project context (see Common: Project Context Resolution). Ask the user only for values not already resolved:
+- **Agent name** — Unique name for the agent
+- **Model deployment** — Model deployment name (e.g., `gpt-4o`)
+- **Instructions** — System prompt (optional)
+- **Temperature** — Response randomness 0-2 (optional, default varies by model)
+- **Tools** — Tool configurations (optional)
+
+### Step 2: Get Agent Definition Schema
+
+Use `agent_definition_schema_get` with `schemaType: prompt` to retrieve the current schema.
+
+### Step 3: Create the Agent
+
+Use `agent_update` with the agent definition:
+
+```json
+{
+  "kind": "prompt",
+  "model": "<model-deployment>",
+  "instructions": "<system-prompt>",
+  "temperature": 0.7
+}
+```
+
+### Step 4: Test the Agent
+
+Read and follow the [invoke skill](../invoke/invoke.md) to send a test message and verify the agent responds correctly.
+
+## Display Agent Information
+Once deployment is done for either hosted or prompt agent, display the agent's details in a nicely formatted table.
+
+Below the table you MUST also display a Playground link for direct access to the agent in Azure AI Foundry:
+
+[Open in Playground](https://ai.azure.com/nextgen/r/{encodedSubId},{resourceGroup},,{accountName},{projectName}/build/agents/{agentName}/build?version={agentVersion})
+
+To calculate the encodedSubId, you need to take subscription id and convert it into its 16-byte GUID, then encode it as URL-safe base64 without padding (= characters trimmed). You can use the following Python code to do this conversion:
+
+```
+python -c "import base64,uuid;print(base64.urlsafe_b64encode(uuid.UUID('<SUBSCRIPTION_ID>').bytes).rstrip(b'=').decode())"
+```
+
+## Document Deployment Context
+
+After a successful deployment, persist the following to a `.env` or config file in the repo so future conversations (e.g., evaluation, monitoring) can pick them up automatically:
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `AZURE_AI_PROJECT_ENDPOINT` | Foundry project endpoint | `https://<account>.services.ai.azure.com/api/projects/<project>` |
+| `AZURE_AI_AGENT_NAME` | Deployed agent name | `my-support-agent` |
+| `AZURE_AI_AGENT_VERSION` | Current agent version | `1` |
+| `AZURE_CONTAINER_REGISTRY` | ACR resource (hosted agents) | `myregistry.azurecr.io` |
+
+If a `.env` file already exists, read it first and merge — do not overwrite existing values without confirmation.
+
+## After Deployment
+
+After a successful deployment, ask the user: *"Would you like to set up evaluation and monitoring for this agent?"*
+
+- **Evaluation & optimization** → follow the [observe skill](../observe/observe.md) to configure evaluators, run batch evaluations, and optimize the agent.
+- **Production trace analysis** → follow the [trace skill](../trace/trace.md) to search conversations, diagnose failures, and analyze latency using App Insights.
+
+## Agent Definition Schemas
+
+### Prompt Agent
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `kind` | string | ✅ | Must be `"prompt"` |
+| `model` | string | ✅ | Model deployment name (e.g., `gpt-4o`) |
+| `instructions` | string | | System message for the model |
+| `temperature` | number | | Response randomness (0-2) |
+| `top_p` | number | | Nucleus sampling (0-1) |
+| `tools` | array | | Tools the model may call |
+| `tool_choice` | string/object | | Tool selection strategy |
+| `rai_config` | object | | Responsible AI configuration |
+
+### Hosted Agent
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `kind` | string | ✅ | Must be `"hosted"` |
+| `image` | string | ✅ | Container image URL |
+| `cpu` | string | ✅ | CPU allocation (e.g., `"0.5"`, `"1"`, `"2"`) |
+| `memory` | string | ✅ | Memory allocation (e.g., `"1Gi"`, `"2Gi"`) |
+| `container_protocol_versions` | array | ✅ | Protocol and version pairs |
+| `environment_variables` | object | | Key-value pairs for container env vars |
+| `tools` | array | | Tool configurations |
+| `rai_config` | object | | Responsible AI configuration |
+
+> **Reminder:** Always pass `creationOptions.metadata.enableVnextExperience: "true"` when creating vNext hosted agents.
+
+### Container Protocols
+
+| Protocol | Description |
+|----------|-------------|
+| `a2a` | Agent-to-Agent protocol |
+| `responses` | OpenAI Responses API |
+| `mcp` | Model Context Protocol |
+
+## Agent Management Operations
+
+### Clone an Agent
+
+Use `agent_update` with `isCloneRequest: true` and `cloneTargetAgentName` to create a copy. For prompt agents, optionally override the model with `modelName`.
+
+### Delete an Agent
+
+Use `agent_delete` — automatically cleans up containers for hosted agents.
+
+### List Agents
+
+Use `agent_get` without `agentName` to list all agents, or with `agentName` to get a specific agent's details.
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Project type not detected | No known project files found | Ask user to specify project type manually |
+| Docker not running | Docker Desktop not started or not installed | Start Docker Desktop, or use Cloud Build (ACR Tasks) instead |
+| ACR login failed | Not authenticated to Azure | Run `az login` first, then `az acr login --name <acr-name>` |
+| Build/push failed | Dockerfile errors or insufficient ACR permissions | Check Dockerfile syntax, verify Contributor or AcrPush role on registry |
+| Agent creation failed | Invalid definition or missing required fields | Use `agent_definition_schema_get` to verify schema, check all required fields |
+| Container start failed | Image not accessible or invalid configuration | Verify ACR image path, check cpu/memory values, confirm ACR permissions |
+| Container status: Failed | Runtime error in container | Check container logs, verify environment variables, ensure image runs correctly |
+| Permission denied | Insufficient Foundry project permissions | Verify Azure AI Owner or Contributor role on the project |
+| Schema fetch failed | Invalid project endpoint | Verify project endpoint URL format: `https://<resource>.services.ai.azure.com/api/projects/<project>` |
+
+## Non-Interactive / YOLO Mode
+
+When running in non-interactive mode (e.g., `nonInteractive: true` or YOLO mode), the skill skips user confirmation prompts and uses sensible defaults:
+
+- **Environment variables** — Uses values resolved from `azd env get-values` and project defaults without prompting for confirmation
+- **Agent name** — Must be provided in the initial user message or derived sensibly from the project context; if missing, the skill fails with an error instead of prompting
+- **Container lifecycle** — Automatically starts the container and polls for `Running` status without user confirmation
+
+> ⚠️ **Warning:** In non-interactive mode, ensure all required values (project endpoint, agent name, ACR image) are provided upfront in the user message or available via `azd env get-values`. Missing values will cause the deployment to fail rather than prompt.
+
+## Additional Resources
+
+- [Foundry Hosted Agents](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/hosted-agents?view=foundry)
+- [Foundry Agent Runtime Components](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/runtime-components?view=foundry)
+- [Foundry Samples](https://github.com/microsoft-foundry/foundry-samples/)

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

@@ -0,0 +1,98 @@
+# Invoke Foundry Agent
+
+Invoke and test deployed agents in Azure AI Foundry with single-turn and multi-turn conversations.
+
+## Quick Reference
+
+| Property | Value |
+|----------|-------|
+| Agent types | Prompt (LLM-based), Hosted (ACA based), Hosted (vNext) |
+| MCP server | `foundry-mcp` |
+| Key MCP tools | `agent_invoke`, `agent_container_status_get`, `agent_get` |
+| Conversation support | Single-turn and multi-turn (via `conversationId`) |
+| Session support | Sticky sessions for vNext hosted agents (via client-generated `sessionId`) |
+
+## When to Use This Skill
+
+- Send a test message to a deployed agent
+- Have multi-turn conversations with an agent
+- Test a prompt agent immediately after creation
+- Test a hosted agent after its container is running
+- Verify an agent responds correctly to specific inputs
+
+## MCP Tools
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `agent_invoke` | Send a message to an agent and get a response | `projectEndpoint`, `agentName`, `inputText` (required); `agentVersion`, `conversationId`, `containerEndpoint`, `sessionId` (mandatory for vNext hosted agents) |
+| `agent_container_status_get` | Check container running status (hosted agents) | `projectEndpoint`, `agentName` (required); `agentVersion` |
+| `agent_get` | Get agent details to verify existence and type | `projectEndpoint` (required), `agentName` (optional) |
+
+## Workflow
+
+### Step 1: Verify Agent Readiness
+
+Delegate the readiness check to a sub-agent. Provide the project endpoint and agent name, and instruct it to:
+
+**Prompt agents** → Use `agent_get` to verify the agent exists.
+
+**Hosted agents (ACA)** → Use `agent_container_status_get` to check:
+- Status `Running` ✅ → Proceed to Step 2
+- Status `Starting` → Wait and re-check
+- Status `Stopped` or `Failed` ❌ → Warn the user and suggest using the deploy skill to start the container
+
+**Hosted agents (vNext)** → Ready immediately after deployment (no container status check needed)
+
+### Step 2: Invoke Agent
+
+Use the project endpoint and agent name from the project context (see Common: Project Context Resolution). Ask the user only for values not already resolved.
+
+Use `agent_invoke` to send a message:
+- `projectEndpoint` — AI Foundry project endpoint
+- `agentName` — Name of the agent to invoke
+- `inputText` — The message to send
+
+**Optional parameters:**
+- `agentVersion` — Target a specific agent version
+- `sessionId` — MANDATORY for vNext hosted agents, include the session ID to maintain sticky sessions with the same compute resource
+
+#### Session Support for vNext Hosted Agents
+In vNext hosted agents, the invoke endpoint accepts a 25 character alphanumeric `sessionId` parameter. Sessions are **sticky** - they route the request to same underlying compute resource, so agent can re-use the state stored in compute's file across multiple turns.
+
+Rules:
+1. You MUST generate a unique `sessionId` before making the first `agent_invoke` call.
+2. If you have a session ID, you MUST include it in every subsequent `agent_invoke` call for that conversation.
+3. When the user explicitly requests a new session, create a new `sessionId` and use it for rest of the `agent_invoke` calls.
+
+This is different from `conversationId` which tracks conversation history — `sessionId` controls which compute instance handles the request.
+
+### Step 3: Multi-Turn Conversations
+
+For follow-up messages, pass the `conversationId` from the previous response to `agent_invoke`. This maintains conversation context across turns.
+
+Each invocation with the same `conversationId` continues the existing conversation thread.
+
+## Agent Type Differences
+
+| Behavior | Prompt Agent | Hosted Agent |
+|----------|-------------|--------------|
+| Readiness | Immediate after creation | Requires running container |
+| Pre-check | `agent_get` to verify exists | `agent_container_status_get` for `Running` status |
+| Routing | Automatic | Optional `containerEndpoint` parameter |
+| Multi-turn | ✅ via `conversationId` | ✅ via `conversationId` |
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Agent not found | Invalid agent name or project endpoint | Use `agent_get` to list available agents and verify name |
+| Container not running | Hosted agent container is stopped or failed | Use deploy skill to start the container with `agent_container_control` |
+| Invocation failed | Model error, timeout, or invalid input | Check agent logs, verify model deployment is active, retry with simpler input |
+| Conversation ID invalid | Stale or non-existent conversation | Start a new conversation without `conversationId` |
+| Rate limit exceeded | Too many requests | Implement backoff and retry, or wait before sending next message |
+
+## Additional Resources
+
+- [Foundry Hosted Agents](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/hosted-agents?view=foundry)
+- [Foundry Agent Runtime Components](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/runtime-components?view=foundry)
+- [Foundry Samples](https://github.com/azure-ai-foundry/foundry-samples)