Início rápido: Implemente o seu próprio código como agente hospedado

Em Implementar o seu primeiro agente alojado, implementou um exemplo. Neste quickstart, implementa o seu próprio código de agente em Python ou .NET (C#) para o Foundry Agent Service. O seu código pode usar qualquer framework de agentes – como o Microsoft Agent Framework, LangGraph, o GitHub Copilot SDK ou o OpenAI Agents SDK – ou código simples que chame um modelo diretamente.

Cada passo de código inclui separadores para a sua linguagem e protocolo. Selecione a mesma combinação, como C# (Respostas), em cada passo.

Se usar um agente de programação como o GitHub Copilot, o Microsoft Foundry Skill pode ajudar a adaptar o quickstart à sua própria base de código e a executar os passos corretos azd de implementação.

Pré-requisitos

Antes de começar, você precisa:

• Uma subscrição Azure--Crie uma gratuitamente.

• Se já tiver um projeto Foundry, precisa de Foundry Project Manager ao nível do projeto. Se precisares de criar um novo projeto do Foundry, precisas da função Owner ao nível do grupo de recursos. Para a matriz completa de funções, veja Referência de permissões de 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 seu código de agente existente num diretório local.

• Para o caminho Python, Python 3.13 ou posterior.

• Para o caminho C#, o SDK .NET 10 ou posterior.

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

O diretório do seu projeto deve conter, pelo menos, 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 a sua estrutura

A biblioteca de alojamento que adicionas no Step 1 trata do protocolo – o servidor HTTP, as verificações de saúde e os esquemas de pedidos e respostas. Não depende de um framework de agentes específico, por isso a lógica do teu agente pode usar quaisquer pacotes que prefiras, em Python ou C#.

Para usar um framework, adiciona os seus pacotes ao lado da biblioteca host, depois chama o framework a partir do handler. A tabela seguinte lista as escolhas comuns e um exemplo de Python para cada uma.

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

A requirements.txt de cada amostra lista as versões exatas dos pacotes. Para o conjunto completo de exemplos para trazer os seus próprios exemplos, consulte a pasta de exemplos Python.

Para C#, adiciona pacotes framework ao ficheiro do teu projeto ao lado do pacote de alojamento, depois chama o framework a partir do handler em Program.cs. Para o conjunto completo de exemplos de C#, consulte a pasta de exemplos “bring-your-own” de C#.

Note

O Microsoft Agent Framework tem uma integração de alojamento integrada que utiliza o seu próprio pacote. Para implementar um agente do Microsoft Agent Framework, consulte Implementar o seu primeiro agente alojado.

Comece a partir de um exemplo no Visual Studio Code

Para começar a partir de um modelo de framework funcional em vez do seu próprio código, use a galeria de exemplos no Microsoft Foundry Toolkit for Visual Studio Code:

1. Na Barra de Atividades do Visual Studio Code, selecione o ícone do Foundry Toolkit.
2. Em Ferramentas de Desenvolvimento>Ferramentas de Desenvolvimento do Agente, selecione Criar agente.
3. Em Criar em código com controlo total, selecione Usar uma amostra.
4. No Criar agente alojado a partir de exemplo, use os filtros para limitar a galeria:
   • Para 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. Seleciona uma amostra e depois seleciona Próximo.
6. Introduza o nome de um agente, selecione o seu projeto Foundry e depois selecione Criar.

O kit de ferramentas estrutura a amostra para um novo espaço de trabalho e configura uma experiência de depuração F5 com um clique. Para instalar dependências, testar localmente e implementar a partir do Visual Studio Code, siga os passos do Visual Studio Code em Deployar o seu primeiro agente alojado.

Escolha o seu protocolo

Cada passo de código tem um separador para cada combinação de linguagem e protocolo. O Answers gere o histórico de conversas e é compatível com OpenAI. Invocations dá-lhe controlo total sobre os esquemas de pedido e de resposta. Selecione a mesma linguagem e combinação de protocolo em cada etapa.

Sugestão

Não tem a certeza de que protocolo usar? Comece pelas Respostas.

Passo 1: Adicionar a biblioteca anfitriã

Adicione a biblioteca de protocolos ao seu projeto. A biblioteca gere o servidor HTTP, as verificações de saúde e a conformidade com protocolos, independentemente do framework de agentes que utiliza. Se usar um framework, adicione os seus pacotes juntamente com a biblioteca de alojamento – veja Escolha o seu framework.

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 protocolos:

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 protocolos:

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

Passo 2: Adicionar o wrapper de hospedagem

Crie ou atualize o ponto de entrada do seu agente com o wrapper de alojamento. Os exemplos seguintes mostram o padrão mínimo. Substitui o bloco marcado pela lógica do teu agente existente.

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

Estes exemplos reproduzem a entrada do utilizador para demonstrar o wrapper de alojamento. Substitua o bloco assinalado pela lógica do seu próprio agente — chamadas ao modelo, RAG ou uma estrutura como o LangGraph ou o GitHub Copilot SDK. Para exemplos completos, veja os exemplos de Python e C#.

Passo 3: Inicializar o projeto

Executa azd ai agent init a partir do diretório de origem do teu agente. A CLI do Azure Developer deteta a sua linguagem a partir dos ficheiros 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: Personaliza o nome ou aceita o padrão.
• Foundry Project: Selecione Usar um project Foundry existente ou Criar um novo project Foundry.
• Assinatura: selecione sua assinatura do Azure.
• Localização: Selecione uma região Azure.

Quando estiver concluído, vê: definição de agente de IA adicionada com sucesso ao seu projeto azd!

Passo 4: Provisionar recursos do Azure

azd provision

Isto cria os recursos necessários do Azure, como o Application Insights.

Passo 5: Testar o agente localmente

azd ai agent run

Este comando cria um ambiente virtual (Python) ou restaura e constrói o projeto (C#), instala dependências e lança o seu agente. Também abre o agente inspector no teu navegador para poderes conversar com o agente.

Também pode invocar a partir da CLI num terminal separado:

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

Passo 6: Implementar no Serviço de Agentes do Foundry

azd deploy

Quando o comando termina, a saída mostra hiperligações para o ambiente de teste do agente e para o ponto final 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

Passo 7: Invocar o agente implementado

azd ai agent invoke "Hello from my hosted agent"

Deves ver uma resposta dentro de alguns segundos.

Limpeza de recursos

Advertência

Se o ambiente atual azd criou o projeto Foundry, azd down apaga permanentemente o grupo de recursos do projeto e tudo o que nele existe. Se selecionou um projeto existente durante a inicialização, azd down deixa o projeto, o seu grupo de recursos, o agente alojado e outros recursos de início rápido no local. Apaga separadamente quaisquer recursos que já não precises do projeto existente.

azd down

Troubleshooting

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 está referenciado (dotnet add package Azure.AI.AgentServer.Responses --prerelease ou Azure.AI.AgentServer.Invocations) e que o projeto utiliza o web SDK (dotnet new web).
C#: Cannot resolve scoped service ... Handler from root provider em dotnet run	O perfil de lançamento predefinido dotnet new web define ASPNETCORE_ENVIRONMENT=Development, o que ativa a validação estrita do âmbito. Utilize azd ai agent run para testar (é executado no modo alojado), ou defina ASPNETCORE_ENVIRONMENT=Production antes de dotnet run.
FOUNDRY_PROJECT_ENDPOINT not set	Use azd ai agent run (define automaticamente) em vez de correr a aplicação diretamente. Ou adiciona-o ao teu .env ficheiro.
Connection refused em execução local	Certifique-se de que nenhum outro processo está a usar a porta 8088.
AuthorizationFailed Durante o destacamento	Precisa de Foundry Project Manager ao nível do projeto.
Agente preso provisioning	Corre azd ai agent show para verificar o estado. As primeiras implantações podem demorar 2–3 minutos enquanto as dependências são instaladas.
azd ai agent init falha	Corre azd version para verificar a versão 1.27.1 ou posterior. Execute azd ext show azure.ai.agents para verificar se tem a versão 1.0.0-beta.4 ou posterior. Atualize com azd ext upgrade azure.ai.agents.

Para a matriz completa de permissões e atribuição de funções, veja Referência de permissões de agente hospedado.

O que aprendeste

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

• Adicionei uma biblioteca de alojamento ao teu código de agente existente.
• Inicializou um projeto azd a partir do diretório de origem.
• Testado localmente com azd ai agent run e azd ai agent invoke --local.
• Implementado no Foundry Agent Service com azd deploy.

Passos seguintes

Gerir o ciclo de vida do agente hospedado

• Constrói uma caixa de ferramentas e usa-a com um agente alojado para combinar ferramentas num único endpoint gerido.

Conteúdo relacionado

• O que são agentes hospedados?
• Implementar um agente alojado a partir do código-fonte
• Implementar um agente hospedado a partir de um contentor
• Ciclo de vida do desenvolvimento do agente
• Amostras de agentes hospedados em Python
• Exemplos para integrares o teu próprio framework (LangGraph, GitHub Copilot SDK, entre outros)
• Amostras de agentes hospedados em C#