diff --git a/plugins/azure-skills/skills/microsoft-foundry/SKILL.md b/plugins/azure-skills/skills/microsoft-foundry/SKILL.md index 9ca2710df..5f3738c4a 100644 --- a/plugins/azure-skills/skills/microsoft-foundry/SKILL.md +++ b/plugins/azure-skills/skills/microsoft-foundry/SKILL.md @@ -260,15 +260,15 @@ Treat an `azure.yaml` service with `host: azure.ai.agent` as Hosted. Use `agent_ - Prefer azd for Hosted Agents and Foundry MCP for Prompt Agents. - Reference official Microsoft documentation URLs instead of embedding CLI command syntax +## Azure Authentication + +- [Azure Authentication Best Practices](references/auth-best-practices.md) + ## 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) -## SDK Quick Reference - -- [Python](references/sdk/foundry-sdk-py.md) - ## Network Isolation Errors Applies to **any** call against a Foundry project or its parent Foundry account — Foundry MCP tools, `azd`, `az` CLI, `curl`, REST, or SDK. diff --git a/plugins/azure-skills/skills/microsoft-foundry/references/sdk/foundry-sdk-py.md b/plugins/azure-skills/skills/microsoft-foundry/references/sdk/foundry-sdk-py.md deleted file mode 100644 index 9e53dacc4..000000000 --- a/plugins/azure-skills/skills/microsoft-foundry/references/sdk/foundry-sdk-py.md +++ /dev/null @@ -1,265 +0,0 @@ -# Microsoft Foundry - Python SDK Guide - -Python-specific implementations for working with Microsoft Foundry. - -**Table of Contents:** [Prerequisites](#prerequisites) · [Model Discovery and Deployment](#model-discovery-and-deployment-mcp) · [RAG Agent with Azure AI Search](#rag-agent-with-azure-ai-search) · [Creating Agents](#creating-agents) · [Agent Evaluation](#agent-evaluation) · [Knowledge Index Operations](#knowledge-index-operations-mcp) · [Best Practices](#best-practices) · [Error Handling](#error-handling) - -## Prerequisites - -```bash -pip install azure-ai-projects azure-identity azure-ai-inference openai azure-ai-evaluation python-dotenv -``` - -### Environment Variables - -```bash -PROJECT_ENDPOINT=https://.services.ai.azure.com/api/projects/ -MODEL_DEPLOYMENT_NAME=gpt-4o -AZURE_AI_SEARCH_CONNECTION_NAME=my-search-connection -AI_SEARCH_INDEX_NAME=my-index -AZURE_OPENAI_ENDPOINT=https://.openai.azure.com -AZURE_OPENAI_DEPLOYMENT=gpt-4o -``` - -## Model Discovery and Deployment (MCP) - -```python -foundry_models_list() # All models -foundry_models_list(publisher="OpenAI") # Filter by publisher -foundry_models_list(search_for_free_playground=True) # Free playground models - -foundry_models_deploy( - resource_group="my-rg", deployment="gpt-4o-deployment", - model_name="gpt-4o", model_format="OpenAI", - azure_ai_services="my-foundry-resource", - model_version="2024-05-13", sku_capacity=10, scale_type="Standard" -) -``` - -## RAG Agent with Azure AI Search - -> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](../auth-best-practices.md) for production patterns. - -```python -import os -from azure.ai.projects import AIProjectClient -from azure.identity import DefaultAzureCredential -from azure.ai.agents.models import ( - AzureAISearchToolDefinition, AzureAISearchToolResource, - AISearchIndexResource, AzureAISearchQueryType, -) - -project_client = AIProjectClient( - endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"], - credential=DefaultAzureCredential(), -) - -azs_connection = project_client.connections.get( - os.environ["AZURE_AI_SEARCH_CONNECTION_NAME"] -) - -agent = project_client.agents.create_agent( - model=os.environ["FOUNDRY_MODEL_DEPLOYMENT_NAME"], - name="RAGAgent", - instructions="You are a helpful assistant. Use the knowledge base to answer. " - "Provide citations as: `[message_idx:search_idx†source]`.", - tools=[AzureAISearchToolDefinition( - azure_ai_search=AzureAISearchToolResource(indexes=[ - AISearchIndexResource( - index_connection_id=azs_connection.id, - index_name=os.environ["AI_SEARCH_INDEX_NAME"], - query_type=AzureAISearchQueryType.HYBRID, - ), - ]) - )], -) -``` - -### Querying a RAG Agent (Streaming) - -```python -openai_client = project_client.get_openai_client() - -stream = openai_client.responses.create( - stream=True, tool_choice="required", input="Your question here", - extra_body={"agent": {"name": agent.name, "type": "agent_reference"}}, -) -for event in stream: - if event.type == "response.output_text.delta": - print(event.delta, end="", flush=True) - elif event.type == "response.output_item.done": - if event.item.type == "message" and event.item.content[-1].type == "output_text": - for ann in event.item.content[-1].annotations: - if ann.type == "url_citation": - print(f"\nCitation: {ann.url}") -``` - -## Creating Agents - -### Basic Agent - -```python -agent = project_client.agents.create_agent( - model=os.environ["MODEL_DEPLOYMENT_NAME"], - name="my-agent", - instructions="You are a helpful assistant.", -) -``` - -### Agent with Custom Function Tools - -```python -from azure.ai.agents.models import FunctionTool, ToolSet - -def get_weather(location: str, unit: str = "celsius") -> str: - """Get the current weather for a location.""" - return f"Sunny and 22°{unit[0].upper()} in {location}" - -functions = FunctionTool([get_weather]) -toolset = ToolSet() -toolset.add(functions) - -agent = project_client.agents.create_agent( - model=os.environ["MODEL_DEPLOYMENT_NAME"], - name="function-agent", - instructions="You are a helpful assistant with tool access.", - toolset=toolset, -) -``` - -### Agent with Web Search - -```python -from azure.ai.projects.models import ( - PromptAgentDefinition, WebSearchPreviewTool, ApproximateLocation, -) - -agent = project_client.agents.create_version( - agent_name="WebSearchAgent", - definition=PromptAgentDefinition( - model=os.environ["MODEL_DEPLOYMENT_NAME"], - instructions="Search the web for current information. Provide sources.", - tools=[ - WebSearchPreviewTool( - user_location=ApproximateLocation( - country="US", city="Seattle", region="Washington" - ) - ) - ], - ), -) -``` - -> 💡 **Tip:** `WebSearchPreviewTool` requires no external resource or connection. For Bing Grounding (which requires a dedicated Bing resource and project connection), see [Bing Grounding reference](../../foundry-agent/create/references/tools/prompt-agent/tool-bing-grounding.md). - -### Interacting with Agents - -```python -from azure.ai.agents.models import ListSortOrder - -thread = project_client.agents.threads.create() -project_client.agents.messages.create(thread_id=thread.id, role="user", content="Hello") - -run = project_client.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id) -if run.status == "failed": - print(f"Run failed: {run.last_error}") - -messages = project_client.agents.messages.list(thread_id=thread.id, order=ListSortOrder.ASCENDING) -for msg in messages: - if msg.text_messages: - print(f"{msg.role}: {msg.text_messages[-1].text.value}") - -project_client.agents.delete_agent(agent.id) -``` - -## Agent Evaluation - -### Single Response Evaluation (MCP) - -```python -foundry_agents_query_and_evaluate( - agent_id="", query="What's the weather?", - endpoint="https://my-foundry.services.ai.azure.com/api/projects/my-project", - azure_openai_endpoint="https://my-openai.openai.azure.com", - azure_openai_deployment="gpt-4o", - evaluators="intent_resolution,task_adherence,tool_call_accuracy" -) - -foundry_agents_evaluate( - query="What's the weather?", response="Sunny and 22°C.", - evaluator="intent_resolution", - azure_openai_endpoint="https://my-openai.openai.azure.com", - azure_openai_deployment="gpt-4o" -) -``` - -### Batch Evaluation - -```python -from azure.ai.evaluation import AIAgentConverter, IntentResolutionEvaluator, evaluate - -converter = AIAgentConverter(project_client) -converter.prepare_evaluation_data(thread_ids=["t1", "t2", "t3"], filename="eval_data.jsonl") - -result = evaluate( - data="eval_data.jsonl", - evaluators={ - "intent_resolution": IntentResolutionEvaluator( - azure_openai_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"], - azure_openai_deployment=os.environ["AZURE_OPENAI_DEPLOYMENT"] - ), - }, - output_path="./eval_results" -) -print(f"Results: {result['studio_url']}") -``` - -> 💡 **Tip:** Continuous evaluation requires project managed identity with **Foundry User** role and Application Insights connected to the project. - -## Knowledge Index Operations (MCP) - -```python -foundry_knowledge_index_list(endpoint="") -foundry_knowledge_index_schema(endpoint="", index="my-index") -``` - -## Best Practices - -1. **Never hardcode credentials** — use environment variables and `python-dotenv` -2. **Check `run.status`** and handle `HttpResponseError` exceptions -3. **Reuse `AIProjectClient`** instances — don't create new ones per request -4. **Use type hints** in custom functions for better tool integration -5. **Use context managers** for agent cleanup - -## Error Handling - -```python -from azure.core.exceptions import HttpResponseError - -try: - agent = project_client.agents.create_agent( - model=os.environ["MODEL_DEPLOYMENT_NAME"], - name="my-agent", instructions="You are helpful." - ) -except HttpResponseError as e: - if e.status_code == 429: - print("Rate limited — wait and retry with exponential backoff.") - elif e.status_code == 401: - print("Authentication failed — check credentials.") - else: - print(f"Error: {e.message}") -``` - -### Context Manager for Agent Cleanup - -```python -from contextlib import contextmanager - -@contextmanager -def temporary_agent(project_client, **kwargs): - agent = project_client.agents.create_agent(**kwargs) - try: - yield agent - finally: - project_client.agents.delete_agent(agent.id) -``` diff --git a/tests/microsoft-foundry/__snapshots__/triggers.test.ts.snap b/tests/microsoft-foundry/__snapshots__/triggers.test.ts.snap index 756f8f544..ea5827f0d 100644 --- a/tests/microsoft-foundry/__snapshots__/triggers.test.ts.snap +++ b/tests/microsoft-foundry/__snapshots__/triggers.test.ts.snap @@ -8,6 +8,7 @@ exports[`microsoft-foundry - Trigger Tests Trigger Keywords Snapshot skill descr "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", @@ -88,6 +89,7 @@ exports[`microsoft-foundry - Trigger Tests Trigger Keywords Snapshot skill keywo "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", diff --git a/tests/microsoft-foundry/finetuning/__snapshots__/triggers.test.ts.snap b/tests/microsoft-foundry/finetuning/__snapshots__/triggers.test.ts.snap index f4b23aaef..f5b1a0f04 100644 --- a/tests/microsoft-foundry/finetuning/__snapshots__/triggers.test.ts.snap +++ b/tests/microsoft-foundry/finetuning/__snapshots__/triggers.test.ts.snap @@ -8,6 +8,7 @@ exports[`finetuning - Trigger Tests Trigger Keywords Snapshot skill description "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", @@ -88,6 +89,7 @@ exports[`finetuning - Trigger Tests Trigger Keywords Snapshot skill keywords mat "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", diff --git a/tests/microsoft-foundry/foundry-agent/eval-datasets/__snapshots__/triggers.test.ts.snap b/tests/microsoft-foundry/foundry-agent/eval-datasets/__snapshots__/triggers.test.ts.snap index e1b4b726b..403cbd27d 100644 --- a/tests/microsoft-foundry/foundry-agent/eval-datasets/__snapshots__/triggers.test.ts.snap +++ b/tests/microsoft-foundry/foundry-agent/eval-datasets/__snapshots__/triggers.test.ts.snap @@ -8,6 +8,7 @@ exports[`eval-datasets - Trigger Tests Trigger Keywords Snapshot skill descripti "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", @@ -88,6 +89,7 @@ exports[`eval-datasets - Trigger Tests Trigger Keywords Snapshot skill keywords "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", diff --git a/tests/microsoft-foundry/foundry-agent/observe/__snapshots__/triggers.test.ts.snap b/tests/microsoft-foundry/foundry-agent/observe/__snapshots__/triggers.test.ts.snap index d382be04e..00cd9171e 100644 --- a/tests/microsoft-foundry/foundry-agent/observe/__snapshots__/triggers.test.ts.snap +++ b/tests/microsoft-foundry/foundry-agent/observe/__snapshots__/triggers.test.ts.snap @@ -8,6 +8,7 @@ exports[`observe - Trigger Tests Trigger Keywords Snapshot skill description tri "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", @@ -88,6 +89,7 @@ exports[`observe - Trigger Tests Trigger Keywords Snapshot skill keywords match "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", diff --git a/tests/microsoft-foundry/foundry-agent/trace/__snapshots__/triggers.test.ts.snap b/tests/microsoft-foundry/foundry-agent/trace/__snapshots__/triggers.test.ts.snap index 39a30c2a0..31d3e60e1 100644 --- a/tests/microsoft-foundry/foundry-agent/trace/__snapshots__/triggers.test.ts.snap +++ b/tests/microsoft-foundry/foundry-agent/trace/__snapshots__/triggers.test.ts.snap @@ -8,6 +8,7 @@ exports[`trace - Trigger Tests Trigger Keywords Snapshot skill description trigg "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", @@ -88,6 +89,7 @@ exports[`trace - Trigger Tests Trigger Keywords Snapshot skill keywords match sn "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", diff --git a/tests/microsoft-foundry/models/deploy/capacity/__snapshots__/triggers.test.ts.snap b/tests/microsoft-foundry/models/deploy/capacity/__snapshots__/triggers.test.ts.snap index e099227a9..5d664d66a 100644 --- a/tests/microsoft-foundry/models/deploy/capacity/__snapshots__/triggers.test.ts.snap +++ b/tests/microsoft-foundry/models/deploy/capacity/__snapshots__/triggers.test.ts.snap @@ -8,6 +8,7 @@ exports[`capacity - Trigger Tests Trigger Keywords Snapshot skill description tr "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", @@ -88,6 +89,7 @@ exports[`capacity - Trigger Tests Trigger Keywords Snapshot skill keywords match "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", diff --git a/tests/microsoft-foundry/models/deploy/customize-deployment/__snapshots__/triggers.test.ts.snap b/tests/microsoft-foundry/models/deploy/customize-deployment/__snapshots__/triggers.test.ts.snap index 756f8f544..ea5827f0d 100644 --- a/tests/microsoft-foundry/models/deploy/customize-deployment/__snapshots__/triggers.test.ts.snap +++ b/tests/microsoft-foundry/models/deploy/customize-deployment/__snapshots__/triggers.test.ts.snap @@ -8,6 +8,7 @@ exports[`microsoft-foundry - Trigger Tests Trigger Keywords Snapshot skill descr "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", @@ -88,6 +89,7 @@ exports[`microsoft-foundry - Trigger Tests Trigger Keywords Snapshot skill keywo "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", diff --git a/tests/microsoft-foundry/models/deploy/deploy-model-optimal-region/__snapshots__/triggers.test.ts.snap b/tests/microsoft-foundry/models/deploy/deploy-model-optimal-region/__snapshots__/triggers.test.ts.snap index 756f8f544..ea5827f0d 100644 --- a/tests/microsoft-foundry/models/deploy/deploy-model-optimal-region/__snapshots__/triggers.test.ts.snap +++ b/tests/microsoft-foundry/models/deploy/deploy-model-optimal-region/__snapshots__/triggers.test.ts.snap @@ -8,6 +8,7 @@ exports[`microsoft-foundry - Trigger Tests Trigger Keywords Snapshot skill descr "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", @@ -88,6 +89,7 @@ exports[`microsoft-foundry - Trigger Tests Trigger Keywords Snapshot skill keywo "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", diff --git a/tests/microsoft-foundry/models/deploy/deploy-model/__snapshots__/triggers.test.ts.snap b/tests/microsoft-foundry/models/deploy/deploy-model/__snapshots__/triggers.test.ts.snap index 756f8f544..ea5827f0d 100644 --- a/tests/microsoft-foundry/models/deploy/deploy-model/__snapshots__/triggers.test.ts.snap +++ b/tests/microsoft-foundry/models/deploy/deploy-model/__snapshots__/triggers.test.ts.snap @@ -8,6 +8,7 @@ exports[`microsoft-foundry - Trigger Tests Trigger Keywords Snapshot skill descr "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", @@ -88,6 +89,7 @@ exports[`microsoft-foundry - Trigger Tests Trigger Keywords Snapshot skill keywo "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", diff --git a/tests/microsoft-foundry/resource/create/__snapshots__/triggers.test.ts.snap b/tests/microsoft-foundry/resource/create/__snapshots__/triggers.test.ts.snap index 1a5ed54b7..743b5a7d5 100644 --- a/tests/microsoft-foundry/resource/create/__snapshots__/triggers.test.ts.snap +++ b/tests/microsoft-foundry/resource/create/__snapshots__/triggers.test.ts.snap @@ -8,6 +8,7 @@ exports[`microsoft-foundry:resource/create - Trigger Tests Trigger Keywords Snap "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy", @@ -87,6 +88,7 @@ exports[`microsoft-foundry:resource/create - Trigger Tests Trigger Keywords Snap "agents", "ai", "assignment", + "authentication", "availability", "azure", "azure-deploy",