Início Rápido: Implantar seu próprio código como um agente hospedado

Em Implante seu primeiro agente hospedado, você implantou um exemplo. Neste guia de início rápido, você implanta seu próprio código de agente em Python ou .NET (C#) no Foundry Agent Service. Seu código pode usar qualquer framework de agentes, como Microsoft Agent Framework, LangGraph, o GitHub Copilot SDK ou o OpenAI Agents SDK — ou código simples que chama um modelo diretamente.

Cada etapa de código tem guias para seu idioma e protocolo. Selecione a mesma combinação, como C# (Respostas), em cada etapa.

Se você usar um agente de codificação como GitHub Copilot, o Microsoft Foundry Skill poderá ajudar a adaptar o início rápido à sua própria base de código e executar as etapas de implantação corretasazd.

Pré-requisitos

Antes de começar, você precisa de:

• Uma assinatura AzureCriar uma gratuitamente.

• Se você tiver um projeto do Foundry existente, precisará de Foundry Project Manager no escopo do projeto. Se você precisar criar um novo projeto no Foundry, precisará da função Owner no escopo do grupo de recursos. Para obter a matriz de função completa, consulte a referência de permissões do agente hospedado.

• Azure Developer CLI (azd) 1.27.1 ou posterior.

• A extensão azd microsoft.foundry:

  azd ext install microsoft.foundry
  

• Uma sessão autenticada azd :

  azd auth login
  

• O código existente do seu agente em um diretório local.

• Para o caminho Python, Python 3.13 ou posterior.

• Para a opção C#, é necessário o .NET 10 SDK ou posterior.

• (Opcional) Para começar a partir de um exemplo em Visual Studio Code, instale Visual Studio Code e o Microsoft Foundry Toolkit for Visual Studio Code.

O diretório do projeto deve conter, no mínimo, para Python:

my-agent/
├── main.py              # Your agent entry point
└── requirements.txt     # Python dependencies

Ou, para C#, um projeto Web .NET:

my-agent/
├── Program.cs           # Your agent entry point
└── my-agent.csproj      # Project file (web SDK)

Escolha sua estrutura

A biblioteca de hospedagem que você adiciona na Etapa 1 manipula o protocolo – o servidor HTTP, verificações de integridade e esquemas de solicitação e resposta. Ela não depende de uma estrutura de agente específica, portanto, a lógica do agente pode usar todos os pacotes que você preferir, em Python ou C#.

Para usar uma estrutura, adicione seus pacotes ao lado da biblioteca de hospedagem e chame a estrutura do manipulador. A tabela a seguir lista as opções comuns e um exemplo de Python para cada uma.

Framework	Pacotes a serem adicionados a requirements.txt	Amostra
Python simples (chame um modelo diretamente)	azure-ai-projects	olá, mundo
LangGraph	langgraph, langchain-azure-ai	langgraph-chat
SDK do GitHub Copilot	github-copilot-sdk	github-copilot
SDK de agentes do OpenAI	openai-agents	openai-agents-sdk

Cada exemplo lista as versões exatas do requirements.txt pacote. Para ver o conjunto completo de exemplos do tipo bring-your-own, consulte a pasta de exemplos em Python.

Para C#, adicione pacotes de estrutura ao arquivo de projeto ao lado do pacote de hospedagem e, em seguida, chame a estrutura do manipulador em Program.cs. Para obter o conjunto completo de exemplos de C#, consulte a pasta de exemplos traga seu próprio C#.

Note

Microsoft Agent Framework tem uma integração interna de hospedagem que usa seu próprio pacote. Para implantar um agente do Microsoft Agent Framework, consulte Implantar seu primeiro agente hospedado.

Comece com um exemplo em Visual Studio Code

Para começar a partir de um modelo de estrutura de trabalho em vez de seu próprio código, use a galeria de exemplo no Microsoft Foundry Toolkit para Visual Studio Code:

1. Na barra de atividades do Visual Studio Code, selecione o ícone Foundry Toolkit.
2. Em Ferramentas do desenvolvedor>Ferramentas de desenvolvimento do agente, selecione Criar agente.
3. Em Criar no código com controle total, selecione Usar um exemplo.
4. Em Criar Agente Hospedado a partir de Exemplo, use os filtros para refinar a galeria:
   • Para o Framework, selecione Agent Framework, Bring Your Own, LangGraph ou Copilot SDK.
   • Para Tipo de Protocolo, selecione API de Respostas ou API de Invocações.
5. Selecione um exemplo e selecione Avançar.
6. Insira um nome de agente, selecione seu projeto foundry e, em seguida, selecione Criar.

O kit de ferramentas prepara o exemplo em um novo espaço de trabalho e configura uma experiência de depuração F5 com um único clique. Para instalar dependências, testar localmente e implantar de Visual Studio Code, siga as etapas de Visual Studio Code em Implantar seu primeiro agente hospedado.

Escolha seu protocolo

Cada etapa de código tem uma guia para cada combinação de idioma e protocolo. As respostas gerenciam o histórico de conversas e são compatíveis com OpenAI. Invocations oferece controle total sobre os esquemas de requisição e resposta. Selecione a mesma combinação de idioma e protocolo em cada etapa.

Dica

Não tem certeza de qual protocolo usar? Comece com respostas.

Etapa 1: Adicionar a biblioteca de hospedagem

Adicione a biblioteca de protocolos ao seu projeto. A biblioteca manipula o servidor HTTP, as verificações de integridade e a conformidade do protocolo, independentemente da estrutura do agente que você usa. Se você usar uma estrutura, adicione seus pacotes junto com a biblioteca de hospedagem . Consulte Escolher sua estrutura.

Python (respostas)

Adicione a biblioteca de protocolos ao seu requirements.txt:

azure-ai-agentserver-responses>=1.0.0b7

Python (Invocações)

Adicione a biblioteca de protocolos ao seu requirements.txt:

azure-ai-agentserver-invocations>=1.0.0b5

C# (respostas)

Crie um projeto Web .NET e adicione o pacote de protocolo:

dotnet new web --name my-agent
cd my-agent
dotnet add package Azure.AI.AgentServer.Responses --prerelease

C# (Invocações)

Crie um projeto Web .NET e adicione o pacote de protocolo:

dotnet new web --name my-agent
cd my-agent
dotnet add package Azure.AI.AgentServer.Invocations --prerelease

Etapa 2: Adicionar o wrapper de hospedagem

Crie ou atualize o ponto de entrada do agente com o wrapper de hospedagem. Os exemplos a seguir mostram o padrão mínimo. Substitua o bloco marcado pela lógica existente do agente.

Python (respostas)

Criar ou atualizar main.py:

import asyncio
from azure.ai.agentserver.responses import (
    CreateResponse,
    ResponseContext,
    ResponsesAgentServerHost,
    TextResponse,
)

app = ResponsesAgentServerHost()


@app.response_handler
async def handler(
    request: CreateResponse,
    context: ResponseContext,
    _cancellation_signal: asyncio.Event,
):
    user_input = await context.get_input_text() or ""

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_input}"
    # ─────────────────────────────

    return TextResponse(context, request, text=reply)


app.run()

Python (Invocações)

Criar ou atualizar main.py:

import json
from starlette.requests import Request
from starlette.responses import JSONResponse
from azure.ai.agentserver.invocations import InvocationAgentServerHost

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    raw = (await request.body()).decode("utf-8").strip()
    try:
        body = json.loads(raw)
        user_message = (
            body.get("message") or body.get("input") or raw
        )
    except json.JSONDecodeError:
        user_message = raw

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_message}"
    # ─────────────────────────────

    return JSONResponse({"reply": reply})


if __name__ == "__main__":
    app.run()

C# (respostas)

Substituir Program.cs:

using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;

ResponsesServer.Run<EchoHandler>();

public sealed class EchoHandler : ResponseHandler
{
    public override IAsyncEnumerable<ResponseStreamEvent> CreateAsync(
        CreateResponse request,
        ResponseContext context,
        CancellationToken cancellationToken)
    {
        return new TextResponse(context, request, createText: async ct =>
        {
            var userInput = await context.GetInputTextAsync(cancellationToken: ct) ?? "";

            // ─── YOUR AGENT LOGIC HERE ───
            var reply = $"Hello! You said: {userInput}";
            // ──────────────────────────────

            return reply;
        });
    }
}

C# (Invocações)

Substituir Program.cs:

using System.Text.Json;
using Azure.AI.AgentServer.Invocations;
using Microsoft.AspNetCore.Http;

InvocationsServer.Run<EchoHandler>();

public sealed class EchoHandler : InvocationHandler
{
    public override async Task HandleAsync(
        HttpRequest request,
        HttpResponse response,
        InvocationContext context,
        CancellationToken cancellationToken)
    {
        var raw = (await new StreamReader(request.Body).ReadToEndAsync(cancellationToken)).Trim();

        string userMessage;
        try
        {
            var body = JsonDocument.Parse(raw).RootElement;
            userMessage =
                (body.TryGetProperty("message", out var m) ? m.GetString() : null)
                ?? (body.TryGetProperty("input", out var input) ? input.GetString() : null)
                ?? raw;
        }
        catch (JsonException)
        {
            userMessage = raw;
        }

        // ─── YOUR AGENT LOGIC HERE ───
        var reply = $"Hello! You said: {userMessage}";
        // ──────────────────────────────

        await response.WriteAsJsonAsync(new { reply }, cancellationToken);
    }
}

Note

Esses exemplos reproduzem a entrada do usuário para demonstrar o wrapper de hospedagem. Substitua o bloco marcado pela lógica de seu próprio agente – chamadas de modelo, RAG ou uma estrutura como o LangGraph ou o SDK do GitHub Copilot. Para obter exemplos completos, consulte os exemplos de Python e C#.

Etapa 3: Inicializar o projeto

Execute azd ai agent init no diretório de origem do agente. A CLI do Desenvolvedor do Azure detecta seu idioma nos arquivos do projeto:

Python (respostas)

azd ai agent init --protocol responses --deploy-mode code

Python (Invocações)

azd ai agent init --protocol invocations --deploy-mode code

C# (respostas)

azd ai agent init --protocol responses --deploy-mode code

C# (Invocações)

azd ai agent init --protocol invocations --deploy-mode code

O fluxo interativo solicita:

• Nome do agente: personalize o nome ou aceite o padrão.
• Projeto Foundry: Selecione Usar um projeto Foundry existente ou Criar um novo projeto Foundry.
• Assinatura: selecione sua assinatura do Azure.
• Local: selecione uma região de Azure.

Quando concluída, você verá: definição do agente de IA adicionada ao seu projeto azd com êxito!

Etapa 4: Provisionar recursos de Azure

azd provision

Isso cria os recursos de Azure necessários, como o Application Insights.

Etapa 5: Testar o agente localmente

azd ai agent run

Esse comando cria um ambiente virtual (Python) ou restaura e cria o projeto (C#), instala dependências e inicia seu agente. Ele também abre o inspetor de agente no navegador para que você possa conversar com o agente.

Você também pode executar pela CLI em um terminal separado:

azd ai agent invoke --local "Hello from my hosted agent"

Etapa 6: Implantar no Serviço do Foundry Agent

azd deploy

Quando o comando termina, a saída mostra links para o playground do agente e o ponto de extremidade do agente:

Deploying services (azd deploy)

  Done: Deploying service my-agent
  - Agent playground (portal): https://ai.azure.com/.../build/agents/my-agent/build?version=1
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/my-agent/versions/1

Etapa 7: Invocar o agente implantado

azd ai agent invoke "Hello from my hosted agent"

Você deverá ver uma resposta dentro de alguns segundos.

Limpar os recursos

Aviso

Se o ambiente atual azd criou o projeto Foundry, azd down exclui permanentemente o grupo de recursos do projeto e tudo o que está nele. Se você selecionou um projeto existente durante a inicialização, azd down deixa o projeto, seu grupo de recursos, o agente hospedado e outros recursos de início rápido em vigor. Exclua os recursos que você não precisa mais do projeto existente separadamente.

azd down

Solução de problemas

Issue	Solução
ModuleNotFoundError: azure.ai.agentserver	Verifique se a biblioteca de protocolos está dentro requirements.txt e reinstale: pip install -r requirements.txt.
C#: The type or namespace name 'AgentServer' could not be found	Verifique se o pacote de protocolo é referenciado (dotnet add package Azure.AI.AgentServer.Responses --prerelease ou Azure.AI.AgentServer.Invocations) e se o projeto usa o SDK da Web (dotnet new web).
C#: Cannot resolve scoped service ... Handler from root provider em dotnet run	O perfil de inicialização padrão ASPNETCORE_ENVIRONMENT=Development define dotnet new web, o que habilita a validação estrita de escopo. Use azd ai agent run para testar (ele é executado no modo hospedado) ou definido ASPNETCORE_ENVIRONMENT=Production antes dotnet run.
FOUNDRY_PROJECT_ENDPOINT not set	Use azd ai agent run (define-o automaticamente) em vez de executar o aplicativo diretamente. Ou adicione-o ao arquivo .env .
Connection refused em execução local	Verifique se nenhum outro processo está usando a porta 8088.
AuthorizationFailed durante a implantação	Você precisa de Foundry Project Manager no escopo do projeto.
Agente preso em provisioning	Execute azd ai agent show para verificar o status. As primeiras implantações podem levar de 2 a 3 minutos enquanto as dependências são instaladas.
azd ai agent init falha	Execute azd version para verificar 1.27.1 ou posterior. Execute azd ext show azure.ai.agents para verificar 1.0.0-beta.4 ou posterior. Faça upgrade com azd ext upgrade azure.ai.agents.

Para obter a permissão completa e a matriz de atribuição de função, consulte a referência de permissões do agente hospedado.

O que você aprendeu

Neste guia de início rápido, você:

• Adicione uma biblioteca de hospedagem ao seu código de agente existente.
• Foi inicializado um projeto azd a partir do seu diretório de origem.
• Testado localmente com azd ai agent run e azd ai agent invoke --local.
• Implantado no Serviço de Agente do Foundry com azd deploy.

Próximas Etapas 

Gerenciar o ciclo de vida do agente hospedado

• Crie um kit de ferramentas e use-o com um agente hospedado para combinar ferramentas em um único endpoint gerenciado.

Conteúdo relacionado

• O que são agentes hospedados?
• Implantar um agente hospedado do código-fonte
• Implantar um agente hospedado de um contêiner
• Ciclo de vida de desenvolvimento do agente
• Exemplos de agentes hospedados em Python
• Exemplos com seu próprio framework (LangGraph, GitHub Copilot SDK, e muito mais)
• Exemplos de agente hospedado em C#