Uso de Azure Functions con Foundry Agent Service

Instalación del paquete

Instale la biblioteca cliente Azure AI Projects:

pip install "azure-ai-projects>=2.0.0"

Definición de la herramienta y creación de un agente

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AzureFunctionBinding,
    AzureFunctionDefinition,
    AzureFunctionStorageQueue,
    AzureFunctionDefinitionFunction,
    AzureFunctionTool,
    PromptAgentDefinition,
)

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
STORAGE_QUEUE_ENDPOINT = "your_storage_queue_service_endpoint"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Define the Azure Function tool
tool = AzureFunctionTool(
    azure_function=AzureFunctionDefinition(
        input_binding=AzureFunctionBinding(
            storage_queue=AzureFunctionStorageQueue(
                queue_name="get-weather-input-queue",
                queue_service_endpoint=STORAGE_QUEUE_ENDPOINT,
            )
        ),
        output_binding=AzureFunctionBinding(
            storage_queue=AzureFunctionStorageQueue(
                queue_name="get-weather-output-queue",
                queue_service_endpoint=STORAGE_QUEUE_ENDPOINT,
            )
        ),
        function=AzureFunctionDefinitionFunction(
            name="GetWeather",
            description="Get the weather in a location.",
            parameters={
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The location to look up.",
                    }
                },
            },
        ),
    )
)

# Create the agent with the Azure Function tool
agent = project.agents.create_version(
    agent_name="azure-function-agent-get-weather",
    definition=PromptAgentDefinition(
        model="gpt-5.1",
        instructions="You are a helpful support agent. Answer the user's questions to the best of your ability.",
        tools=[tool],
    ),
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

Creación de una respuesta

response = openai.responses.create(
    input="What is the weather in Seattle, WA?",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

print(f"Response: {response.output_text}")

Limpieza

project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)
print("Agent deleted")

Escribe la función de Azure

Los ejemplos de código anteriores muestran cómo definir la herramienta Azure Function en el lado del agente. También debe escribir la función que procesa los mensajes de cola. La función recibe la entrada de la cola de entrada, ejecuta la lógica personalizada y devuelve un resultado a través de la cola de salida.

En el ejemplo siguiente se muestra una función desencadenada por cola que obtiene información meteorológica de una ubicación. La función analiza el mensaje entrante, extrae los argumentos de la función y devuelve una respuesta con un CorrelationId que el agente usa para hacer coincidir el resultado con la solicitud original.

import azure.functions as func
import logging
import json

app = func.FunctionApp()


# Queue trigger receives agent tool calls from the input queue
# and returns results through the output queue binding
@app.queue_trigger(
    arg_name="msg",
    queue_name="get-weather-input-queue",
    connection="STORAGE_CONNECTION",
)
@app.queue_output(
    arg_name="outputQueue",
    queue_name="get-weather-output-queue",
    connection="STORAGE_CONNECTION",
)
def queue_trigger(
    msg: func.QueueMessage, outputQueue: func.Out[str]
):
    try:
        # Parse the incoming message from the agent
        messagepayload = json.loads(
            msg.get_body().decode("utf-8")
        )
        logging.info("Received: %s", json.dumps(messagepayload))

        # Extract the function arguments
        function_args = messagepayload.get("function_args", {})
        location = function_args.get("location")

        # Run your custom logic (replace with real API calls)
        weather_result = (
            f"Weather is {len(location)} degrees "
            f"and sunny in {location}"
        )

        # Return result with the CorrelationId from the request
        response_message = {
            "Value": weather_result,
            "CorrelationId": messagepayload["CorrelationId"],
        }
        outputQueue.set(json.dumps(response_message))

    except Exception as e:
        logging.error("Error processing message: %s", e)

Para obtener el ejemplo completo, consulte ejemplo de clima de Azure Functions en el repositorio SDK de Azure para Python.

Instalación de los paquetes

Instale las bibliotecas cliente de Azure AI Projects:

dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Extensions.OpenAI
dotnet add package Azure.Identity

Definición de la herramienta y creación de un agente

using System;
using System.Text.Json;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var projectEndpoint = "your_project_endpoint";
var storageQueueUri = "your_storage_queue_service_endpoint";

AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

AzureFunctionDefinitionFunction functionDefinition = new(
    name: "GetWeather",
    parameters: BinaryData.FromObjectAsJson(
        new
        {
            Type = "object",
            Properties = new
            {
                location = new
                {
                    Type = "string",
                    Description = "The location to look up.",
                }
            }
        },
        new JsonSerializerOptions() { PropertyNamingPolicy = JsonNamingPolicy.CamelCase }
    )
)
{
    Description = "Get the weather in a location.",
};

AzureFunctionTool azureFnTool = new(
    new AzureFunctionDefinition(
        function: functionDefinition,
        inputBinding: new AzureFunctionBinding(
            new AzureFunctionStorageQueue(
                queueServiceEndpoint: storageQueueUri,
                queueName: "input")),
        outputBinding: new AzureFunctionBinding(
            new AzureFunctionStorageQueue(
                queueServiceEndpoint: storageQueueUri,
                queueName: "output"))
    )
);

DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    Instructions = "You are a helpful support agent. Answer the user's questions "
        + "to the best of your ability.",
    Tools = { azureFnTool },
};

AgentVersion agentVersion = await projectClient.AgentAdministrationClient.CreateAgentVersionAsync(
    agentName: "azure-function-agent-get-weather",
    options: new(agentDefinition));
Console.WriteLine($"Agent created (id: {agentVersion.Id}, name: {agentVersion.Name}, "
    + $"version: {agentVersion.Version})");

Creación de una respuesta

ProjectResponsesClient responseClient =
    projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);

CreateResponseOptions responseOptions = new()
{
    InputItems =
    {
        ResponseItem.CreateUserMessageItem("What is the weather in Seattle, WA?")
    },
};

ResponseResult response = await responseClient.CreateResponseAsync(responseOptions);
Console.WriteLine(response.GetOutputText());

Limpieza

await projectClient.AgentAdministrationClient.DeleteAgentVersionAsync(
    agentName: agentVersion.Name,
    agentVersion: agentVersion.Version);
Console.WriteLine("Agent deleted");

Escribe la función de Azure

Los ejemplos de código anteriores muestran cómo definir la herramienta Azure Function en el lado del agente. También debe escribir la función que procesa los mensajes de cola. La función recibe la entrada de la cola de entrada, ejecuta la lógica personalizada y devuelve un resultado a través de la cola de salida.

En el ejemplo siguiente se muestra una función desencadenada por cola que obtiene información meteorológica de una ubicación. En este ejemplo se usa el modelo de trabajo aislado. La función analiza el mensaje entrante, extrae los argumentos de la función y devuelve una respuesta con un CorrelationId que el agente usa para hacer coincidir el resultado con la solicitud original.

using System.Text.Json;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

public class GetWeather
{
    private readonly ILogger<GetWeather> _logger;

    public GetWeather(ILogger<GetWeather> logger)
    {
        _logger = logger;
    }

    // Queue trigger receives agent tool calls from the input
    // queue and returns results through the output queue
    [Function("GetWeather")]
    [QueueOutput(
        "get-weather-output-queue",
        Connection = "STORAGE_CONNECTION")]
    public string Run(
        [QueueTrigger(
            "get-weather-input-queue",
            Connection = "STORAGE_CONNECTION")]
        string message)
    {
        _logger.LogInformation("Received: {Message}", message);

        // Parse the incoming message from the agent
        var payload = JsonSerializer.Deserialize<JsonElement>(
            message);
        var correlationId = payload
            .GetProperty("CorrelationId").GetString();
        var functionArgs = payload
            .GetProperty("function_args");
        var location = functionArgs
            .GetProperty("location").GetString();

        // Run your custom logic (replace with real API calls)
        var weatherResult =
            $"Weather is {location!.Length} degrees "
            + $"and sunny in {location}";

        // Return result with the CorrelationId from the request
        var response = new
        {
            Value = weatherResult,
            CorrelationId = correlationId,
        };
        return JsonSerializer.Serialize(response);
    }
}

Instalación del paquete

Para agregar la dependencia de Azure AI Agents a su pom.xml:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-agents</artifactId>
    <version>2.0.0</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

Definición de la herramienta y creación de un agente

import com.azure.ai.agents.*;
import com.azure.ai.agents.models.*;
import com.azure.core.util.BinaryData;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

import java.util.*;

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
String projectEndpoint = "your_project_endpoint";
String storageQueueUri = "your_storage_queue_service_endpoint";

AgentsClientBuilder builder = new AgentsClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .endpoint(projectEndpoint)
    .serviceVersion(AgentsServiceVersion.getLatest());

AgentsClient agentsClient = builder.buildAgentsClient();
ResponsesClient responsesClient = builder.buildResponsesClient();

// Define the function parameters
Map<String, BinaryData> parameters = new HashMap<>();
parameters.put("type", BinaryData.fromString("\"object\""));
parameters.put("properties", BinaryData.fromString(
    "{\"location\": {\"type\": \"string\", "
    + "\"description\": \"The location to look up.\"}}"));

AzureFunctionDefinitionDetails function =
    new AzureFunctionDefinitionDetails("GetWeather", parameters)
        .setDescription("Get the weather in a location.");

AzureFunctionTool azureFnTool = new AzureFunctionTool(
    new AzureFunctionDefinition(
        function,
        new AzureFunctionBinding(
            new AzureFunctionStorageQueue(storageQueueUri, "input")),
        new AzureFunctionBinding(
            new AzureFunctionStorageQueue(storageQueueUri, "output"))
    )
);

PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-5.1")
    .setInstructions("You are a helpful support agent. Answer the user's "
        + "questions to the best of your ability.")
    .setTools(Collections.singletonList(azureFnTool));

AgentVersionDetails agent = agentsClient.createAgentVersion(
    "azure-function-agent-get-weather", agentDefinition);
System.out.printf("Agent created (id: %s, name: %s, version: %s)%n",
    agent.getId(), agent.getName(), agent.getVersion());

Creación de una respuesta

AgentReference agentReference = new AgentReference(agent.getName())
    .setVersion(agent.getVersion());

Response response = responsesClient.createAzureResponse(
    new AzureCreateResponseOptions().setAgentReference(agentReference),
    ResponseCreateParams.builder()
        .input("What is the weather in Seattle, WA?"));

System.out.println("Response: " + response.output());

Limpieza

agentsClient.deleteAgentVersion(agent.getName(), agent.getVersion());
System.out.println("Agent deleted");

Escribe la función de Azure

Los ejemplos de código anteriores muestran cómo definir la herramienta Azure Function en el lado del agente. También debe escribir la función que procesa los mensajes de cola. La función recibe la entrada de la cola de entrada, ejecuta la lógica personalizada y devuelve un resultado a través de la cola de salida.

En el ejemplo siguiente se muestra una función desencadenada por cola que obtiene información meteorológica de una ubicación. La función analiza el mensaje entrante, extrae los argumentos de la función y devuelve una respuesta con un CorrelationId que el agente usa para hacer coincidir el resultado con la solicitud original.

import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import com.microsoft.azure.functions.*;
import com.microsoft.azure.functions.annotation.*;

import java.util.logging.Logger;

public class GetWeather {

    // Queue trigger receives agent tool calls from the input
    // queue and returns results through the output queue
    @FunctionName("GetWeather")
    @QueueOutput(
        name = "output",
        queueName = "get-weather-output-queue",
        connection = "STORAGE_CONNECTION")
    public String run(
            @QueueTrigger(
                name = "msg",
                queueName = "get-weather-input-queue",
                connection = "STORAGE_CONNECTION")
            String message,
            final ExecutionContext context) {

        Logger logger = context.getLogger();
        logger.info("Received: " + message);

        // Parse the incoming message from the agent
        JsonObject payload =
            JsonParser.parseString(message)
                .getAsJsonObject();
        String correlationId =
            payload.get("CorrelationId").getAsString();
        JsonObject functionArgs =
            payload.getAsJsonObject("function_args");
        String location =
            functionArgs.get("location").getAsString();

        // Run your custom logic (replace with real API calls)
        String weatherResult =
            "Weather is " + location.length()
            + " degrees and sunny in " + location;

        // Return result with the CorrelationId
        JsonObject response = new JsonObject();
        response.addProperty("Value", weatherResult);
        response.addProperty(
            "CorrelationId", correlationId);
        return response.toString();
    }
}

Instalación de los paquetes

Instale la biblioteca cliente Azure AI Projects:

npm install @azure/ai-projects @azure/identity

Definición de la herramienta y creación de un agente

import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const STORAGE_QUEUE_ENDPOINT = "your_storage_queue_service_endpoint";

// Create clients to call Foundry API
const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
const openai = project.getOpenAIClient();

const agent = await project.agents.createVersion(
  "azure-function-agent-get-weather",
  {
    kind: "prompt",
    model: "gpt-5.1",
    instructions:
      "You are a helpful support agent. Answer the user's questions to the best of your ability.",
    tools: [
      {
        type: "azure_function",
        azure_function: {
          function: {
            name: "GetWeather",
            description: "Get the weather in a location.",
            parameters: {
              type: "object",
              properties: {
                location: {
                  type: "string",
                  description: "The location to look up.",
                },
              },
            },
          },
          input_binding: {
            type: "storage_queue",
            storage_queue: {
              queue_service_endpoint: STORAGE_QUEUE_ENDPOINT,
              queue_name: "get-weather-input-queue",
            },
          },
          output_binding: {
            type: "storage_queue",
            storage_queue: {
              queue_service_endpoint: STORAGE_QUEUE_ENDPOINT,
              queue_name: "get-weather-output-queue",
            },
          },
        },
      },
    ],
  },
);
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

Creación de una respuesta

const response = await openai.responses.create(
  {
    input: "What is the weather in Seattle, WA?",
  },
  {
    body: {
      agent: { name: agent.name, type: "agent_reference" },
    },
  },
);
console.log(`Response: ${response.output_text}`);

Limpieza

await project.agents.deleteVersion(agent.name, agent.version);
console.log("Agent deleted");

Escribe la función de Azure

Los ejemplos de código anteriores muestran cómo definir la herramienta Azure Function en el lado del agente. También debe escribir la función que procesa los mensajes de cola. La función recibe la entrada de la cola de entrada, ejecuta la lógica personalizada y devuelve un resultado a través de la cola de salida.

En el ejemplo siguiente se muestra una función desencadenada por cola que obtiene información meteorológica de una ubicación. En este ejemplo se usa el modelo de programación v4. La función analiza el mensaje entrante, extrae los argumentos de la función y devuelve una respuesta con un CorrelationId que el agente usa para hacer coincidir el resultado con la solicitud original.

import {
  app,
  InvocationContext,
  output,
} from "@azure/functions";

// Define the output queue binding
const queueOutput = output.storageQueue({
  queueName: "get-weather-output-queue",
  connection: "STORAGE_CONNECTION",
});

interface AgentMessage {
  CorrelationId: string;
  function_args: { location: string };
}

// Queue trigger receives agent tool calls from the input
// queue and returns results through the output queue
async function getWeather(
  message: unknown,
  context: InvocationContext
): Promise<void> {
  const payload = message as AgentMessage;
  context.log("Received:", JSON.stringify(payload));

  // Extract the function arguments
  const location = payload.function_args.location;

  // Run your custom logic (replace with real API calls)
  const weatherResult =
    `Weather is ${location.length} degrees ` +
    `and sunny in ${location}`;

  // Return result with the CorrelationId from the request
  const response = {
    Value: weatherResult,
    CorrelationId: payload.CorrelationId,
  };
  context.extraOutputs.set(queueOutput, response);
}

// Register the queue trigger function
app.storageQueue("getWeather", {
  queueName: "get-weather-input-queue",
  connection: "STORAGE_CONNECTION",
  extraOutputs: [queueOutput],
  handler: getWeather,
});

Crear una versión del agente

Cree una versión del agente mediante la definición de la herramienta Azure Function.

curl --request POST \
  --url $FOUNDRY_PROJECT_ENDPOINT/agents/azure-function-agent-get-weather/versions?api-version=$API_VERSION \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Agent with Azure Function tool",
    "definition": {
      "kind": "prompt",
      "model": "gpt-5.1",
      "instructions": "You are a helpful support agent. Answer the user's questions to the best of your ability.",
      "tools": [
        { 
          "type": "azure_function",
          "azure_function": {
              "function": {
                  "name": "GetWeather",
                  "description": "Get the weather in a location.",
                  "parameters": {
                      "type": "object",
                      "properties": {
                          "location": {"type": "string", "description": "The location to look up."}
                      },
                      "required": ["location"]
                  }
              },
              "input_binding": {
                  "type": "storage_queue",
                  "storage_queue": {
                      "queue_service_endpoint": "https://storageaccount.queue.core.windows.net",
                      "queue_name": "input"
                  }
              },
              "output_binding": {
                  "type": "storage_queue",
                  "storage_queue": {
                      "queue_service_endpoint": "https://storageaccount.queue.core.windows.net",
                      "queue_name": "output"
                  }
              }
          }
        }
      ]
    }
  }'

Creación de una respuesta

Cree una respuesta que use la versión del agente para obtener información meteorológica.

curl --request POST \
  --url $FOUNDRY_PROJECT_ENDPOINT/openai/responses?api-version=$API_VERSION \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "What is the weather in Seattle, WA?",
    "agent": {
      "name": "azure-function-agent-get-weather",
      "type": "agent_reference"
    }
  }'

Escribe la función de Azure

Los ejemplos de la API REST muestran cómo configurar la definición de la herramienta función de Azure. La función Azure es código del lado servidor que se escribe en un lenguaje de Functions compatible. Seleccione uno de los otros lenguajes (Python, C#, Java o TypeScript) para ver la implementación de la función.