Merge pull request #314834 from anzaman/release-microsoft-discovery

Model Integration

Author: JillGrant615

articles/microsoft-discovery/concept-discovery-tools.md

@@ -0,0 +1,168 @@
+---
+title: Microsoft Discovery tools and model integration
+description: Learn about tools in Microsoft Discovery, including tool types, how tools are deployed, and how to integrate models into agent workflows using common integration patterns.
+author: anzaman
+ms.author: alzam
+ms.service: azure
+ms.topic: conceptual
+ms.date: 04/17/2026
+---
+
+# Microsoft Discovery tools and model integration
+
+This guide covers how tools work in Microsoft Discovery and how to integrate your models into agent workflows. It explains tool types, integration patterns, and how to get started.
+
+## What are tools?
+
+Tools allow agents to perform specific operations in a repeatable, consistent, and efficient manner. Many operations are already reliably implemented in the form of Software Development Kits (SDK) or Application Programming Interfaces (API). For example, reading and writing to a database happens through a vendor API, which is typically well-documented and optimized. Other examples of where to use a tool include complex or performance-based algorithms or simulations that can't tolerate stochasticity. Tools enable AI models and their agents to direct their workflow reliably and efficiently to interact with existing systems. Examples of tool uses include:
+
+- **Computational tools** provide the necessary algorithms to solve complex mathematical problems, simulate physical phenomena or engineering systems, and analyze large scientific datasets.
+
+- **Data processing tools** manage and refine data collected from various sources. They allow users to extract relevant information, remove noise, and preprocess data for further analysis within the Discovery platform.
+
+- **Simulation tools** can model and simulate physical, chemical, or biological processes, and complex engineering systems using the platform's Supercomputer resources. These tools are crucial for experimentation that can't feasibly be conducted in practice due to constraints such as time, cost, or safety concerns.
+
+- **Visualization tools** interpret scientific data or engineering design data and communicate findings graphically. These tools transform data into graphical representations like charts, graphs, and 3D models, making it easier to explore models, identify patterns, and uncover trends and anomalies.
+
+## Tool types
+
+Microsoft Discovery supports two types of tools: **action** and **code-environment based** tools.
+
+### Action-based tools
+
+Action-based tools are used when the software requires an operating system, such as with commercial, proprietary, or open-source packages. These packages are commonly distributed as binaries or have complex installation requirements. Examples are simulators, emulators, compilers, visualizers, linters, design automation tools, modeling packages, and similar complex software packages.
+
+Tools are installed in a Docker image that is then stored in a container registry. The execution profile of each action the tool should perform, along with arguments, required inputs, and expected outputs, is annotated in the tool's profile. The tool definition's annotations provide the agent with the context of the execution and purpose so that it can effectively plan the invocation.
+
+### Code-environment based tools
+
+A code-environment based tool enables a Microsoft Discovery agent to run custom code or generate an on-demand tool. Any language that the controlling agent can generate and a software development kit is accessible can be used. Code-environment based tools allow an agent to quickly author and execute code. Novel algorithms or dynamically created tools generated by a model are the most likely target scenarios for code-environment based tools.
+
+### Hybrid tools
+
+Code-environment and action-based tools can be combined to create a hybrid tool. Hybrid tools combine action-based tools in container images with code-environment tools dynamically generated by the platform's AI capabilities. Hybrid tools create a dynamic execution environment allowing AI models to generate code that is executed in the structured environment of action-based tools.
+
+## Requirements for authoring tools
+
+Action-based tools must be packaged in a Docker container and stored in a registry accessible to the Microsoft Discovery Supercomputer. A tool definition must be written that has the required specifications. Code-environment based tools also require a tool definition; however, the associated action is directly running the generated code and little else.
+
+## Cardinality and execution profile
+
+Tool definitions can be shared across an entire subscription because the tool definition isn't a unique instantiation. Tools are only instantiated when invoked. Multiple agents can all reference the same tool without conflict as each is instantiated in isolation. As such, care must be taken to ensure that tools don't have any values or data hardcoded either in the profile or the execution profile.
+
+---
+
+## Model integration patterns
+
+Microsoft Discovery provides multiple flexible patterns for integrating scientific machine learning models into its workflows. At a high level, there are four primary approaches, each designed to support different levels of complexity, control, and integration with external systems:
+
+| Pattern | How it works | Where models run | Best for |
+|---|---|---|---|
+| Container-based client tool (Python) | Run custom code inside a container | Foundry or external endpoint | Custom logic and orchestration |
+| Container-based model (Supercomputer) | Run containers in HPC environment | Discovery Supercomputer | Large-scale training/inference |
+| OpenAPI-based | Use REST APIs with schema | Foundry or external service | Existing APIs and services |
+| MCP-based | Exchange structured context | Foundry or external endpoint | Stateful, multi-step workflows |
+
+### Container-based client tool (Python)
+
+In this pattern, the agent invokes a containerized tool that acts as a client for an already deployed model. The container doesn’t host the model itself—instead, it handles communication with the model service, applies any required logic, and returns the final output to the agent. This approach is best when you need precise control over preprocessing, postprocessing, or how multiple steps are orchestrated.
+
+#### How it works
+
+1. Your agent selects the tool  
+2. A container is launched with your inputs  
+3. Your Python script:
+   - Validates and prepares inputs  
+   - Sends a request to the deployed model endpoint 
+   - Applies any custom preprocessing or postprocessing logic
+   - Optionally orchestrates multiple calls or additional steps
+4. Results are returned to the agent  
+
+#### How to set it up
+
+- Deploy a model (e.g., in Foundry or another endpoint)  
+- Build a Docker image with your Python code and push it to your Azure Container Registry (ACR)
+- Configure secure access (managed identity recommended)  
+- Register the container as a tool in Microsoft Discovery  
+
+### Container-based model (Supercomputer)
+
+Package your scientific model into a container and deploy it as a scalable service. This approach is ideal when you need full control over dependencies, runtime, and custom logic. Choose this when your model needs high-performance compute (HPC), such as large-scale training or heavy inference.
+
+#### Key idea
+
+- Your model runs inside a container on the Discovery Supercomputer  
+- Agents don't call it directly—you access it through a tool or service layer  
+
+#### How to set it up
+
+- Package your model and dependencies into a container  
+- Push the image to your Azure Container Registry (ACR)
+- Register is as a tool in Microsoft Discovery
+
+### OpenAPI-based
+
+Expose your model through a standardized API interface and connect it to Discovery using an OpenAPI specification. This is useful when your model is already hosted as a service and you want a standard, schema-driven integration.
+
+#### How it works
+
+- Your model/service is exposed via an HTTP endpoint  
+- You define an OpenAPI (Swagger) spec  
+- Agents use the spec to discover and call operations  
+
+#### How to set it up
+
+- Deploy your model behind an API endpoint  
+- Write an OpenAPI specification (requests, responses, auth)  
+- Register the API as a tool in Foundry  
+
+### MCP-based
+
+Choose this for advanced scenarios that require rich, multi-step, context-aware interactions.
+
+#### How it works
+
+- Your tool implements the Model Context Protocol (MCP)  
+- Agents send and receive structured context  
+- Supports stateful, multi-turn workflows  
+
+#### How to set it up
+
+- Deploy your model behind an endpoint  
+- Use or build an MCP server  
+- Register the MCP tool in Foundry  
+
+## How to choose the right pattern
+
+Use this quick guidance:
+
+- Use **container-based tools** → when you need custom logic around models  
+- Use **Supercomputer (HPC)** → when compute scale is the main constraint  
+- Use **OpenAPI tools** → when you already have REST APIs  
+- Use **MCP tools** → when workflows require memory and context across steps  
+
+> [!NOTE]
+> You can combine multiple patterns in a single workflow.
+
+---
+
+## Security best practices
+
+No matter which pattern you choose, follow these:
+
+- Use **managed identities and RBAC** (avoid hardcoding credentials)  
+- Use **immutable container images** (version and scan them)  
+- Use **encryption** (HTTPS + encrypted storage)  
+- Enable **logging and monitoring** for all tool and model calls  
+
+---
+
+## Related content
+
+- [Microsoft Discovery agents](concept-discovery-agent.md)
+- [What is Azure AI Foundry?](/azure/foundry/what-is-foundry)
+- [Workflows in Microsoft Foundry](/azure/foundry/agents/concepts/workflow)
+- [Get started with containers on Azure](/azure/architecture/containers/container-get-started)
+- [What is Azure RBAC?](/azure/role-based-access-control/overview)
+- [Microsoft OpenAPI documentation](/openapi/)
+- [Microsoft Discovery REST API reference](/rest/api/discovery/)

articles/microsoft-discovery/concept-tools-model-integration.md

@@ -93,11 +93,11 @@ items:
           - name: Discovery Agent types
             href: concept-discovery-agent-types.md
             displayName: Discovery Agent, agent types, prompt agent, workflow agent, orchestration
-      - name: Tools
+      - name: Tools & Models
         items:
-          - name: Discovery Tool concepts
-            href: concept-discovery-tools.md
-            displayName: Discovery Tool, code-environment based tools, action-based tools
+          - name: Tools and model integration
+            href: concept-tools-model-integration.md
+            displayName: Microsoft Discovery, tools, model integration, action-based tools, code-environment based tools, OpenAPI, MCP
       - name: Discovery Engine
         items:
           - name: Discovery Engine overview