Een gehost agentproject initialiseren met de Azure Developer CLI

Gebruik azd ai agent init om een gehost agentproject op te zetten met de bestanden die u nodig hebt om een AI-agent te bouwen, te testen en te implementeren in Microsoft Foundry. In dit artikel kiest u een beginpunt en initialiseert u het project vanuit een sjabloon, vanuit uw eigen code of op basis van een bestaand Foundry-project.

Als u een coderingsagent zoals GitHub Copilot gebruikt, kan de Microsoft Foundry Skill u helpen een beginsjabloon te kiezen, het project te maken en de gegenereerde azd configuratie te interpreteren.

Prerequisites

• De Azure Developer CLI Foundry-extensies geïnstalleerd.
• Een geverifieerde Azure sessie (azd auth login).
• Inzendertoegang voor uw Azure-abonnement.

Een beginpunt kiezen

Er zijn drie manieren om een project te starten. Kies het pad dat overeenkomt met uw situatie.

Initialiseren vanuit een sjabloon

Voer de interactieve wizard uit in een lege map en selecteer Nieuw starten in een sjabloon:

azd ai agent init

De wizard begeleidt u bij de volgende opties.

De naam van de agent is afkomstig van de sjabloon. De CLI maakt een azd omgeving met de naam <directory>-dev en configureert deze met details van het geselecteerde Foundry-project. Elke sjabloon bevat de broncode van de agent, een Dockerfileen een azure.yaml bestand dat fungeert als het geïntegreerde projectmanifest voor de configuratie van het azd project en de gehoste agent.

Initialiseren vanuit een AZURE.yaml-URL

Als u een specifiek voorbeeld van een agent hebt, laat -m dan verwijzen naar de azure.yaml van het voorbeeld. De CLI gebruikt dat bestand als het projectmanifest en downloadt de bron van de agent waarnaar wordt verwezen.

azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml

De -m optie accepteert nog steeds een verouderde manifest-URL van de agent, maar de huidige voorbeelden publiceren een uniforme azure.yaml.

Een model opgeven

Kies een model bij initialisatie:

azd ai agent init --model gpt-4.1

Of gebruik een bestaande modelimplementatie in uw Foundry-project:

azd ai agent init --model-deployment my-deployment

Een implementatiemodus kiezen

Standaard gebruikt azd ai agent init code-implementatie voor Python- en .NET-projecten. Code-implementatie uploadt uw bron als een ZIP-pakket. Als u in plaats daarvan een op containers gebaseerd project wilt genereren, geef dan --deploy-mode container door:

azd ai agent init --deploy-mode container

Als u een vooraf gebouwde containerinstallatiekopie wilt uitrollen, geeft u --image en --agent-name door. Met deze optie worden sjabloon- en taalselectie, code-scaffolding, het genereren van Dockerfile en Azure Container Registry setup overgeslagen.

azd ai agent init --agent-name my-agent --image myregistry.azurecr.io/my-agent:v1

Niet-interactief door sjablonen bladeren

Als u de catalogus wilt bekijken voordat u scaffolding uitvoert, of om azd ai agent init vanuit een script aan te sturen, toont u de catalogus:

# Everything in the catalog
azd ai agent sample list

# Just the featured Python agent samples
azd ai agent sample list --featured-only --language python --type agent

# Full azd templates only, as JSON for scripting
azd ai agent sample list --type azd --output json

Elke vermelding bevat een kant-en-klare initCommand invoer die u kopieert en uitvoert in de map waarin u een scaffold wilt maken.

Initialiseren vanuit bestaande code

Als u bestaande Python of .NET agentcode hebt, voert u deze uit azd ai agent init in de map die uw code al bevat:

cd my-agent/
azd ai agent init

De CLI detecteert de bestaande bestanden en genereert een azure.yaml servicevermelding eromheen zonder uw code te overschrijven. Voor containerimplementatie wordt ook een Dockerfile toegevoegd. Infrastructuur blijft standaard bicep-less, tenzij u de infrastructuur later als code uitwerpt.

Uw agentcode moet voldoen aan het runtimecontract van de gehoste agent:

• Luister op poort 8088.
• Bied een healthcheck aan op GET /readiness.
• Een van de ondersteunde protocollen (responses of invocations) verwerken.

Als uw code nog geen van deze protocollen spreekt, voegt u een protocoladapter toe, een lichtgewicht SDK-wrapper die vertaalt tussen het Foundry-protocol en de logica van uw agent.

Als u een agent wilt toevoegen aan een bestaand azd project, init detecteert u het project en voegt u een nieuwe servicevermelding toe aan uw bestaande azure.yaml. Gebruik --src om een submap op te geven:

azd ai agent init --src src/my-agent

Verbinding maken met een bestaand Foundry-project

Als u een bestaand Foundry-project via azd wilt beheren, start u de wizard en selecteert u de optie om verbinding te maken met een bestaand project. U kunt de interactieve selectie ook overslaan door de Azure resource-id van het project rechtstreeks op te geven:

azd ai agent init --project-id /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}

Als u de project-id wilt vinden, opent u de Foundry-portal, gaat u naar Details beheren>Project en kopieert u de waarde van de resource-id.

Controleren wat er wordt gemaakt

Nadat init is voltooid, bevat uw projectmap de volgende structuur:

.
|-- azure.yaml                  # Unified azd project and hosted agent configuration
|-- src/
|   \-- <agent-name>/
|       |-- Dockerfile          # Container build definition
|       \-- ...                 # Agent source code
|-- .azure/                     # Environment configuration
\-- infra/                      # Optional IaC, created only after you eject infrastructure

Sjablonen en voorbeelden plaatsen een uniforme azure.yaml in de hoofdmap van het project. Tijdens init neemt azd het bestand over of genereert het. Je werkt voortaan met azure.yaml. Infrastructuur is standaard zonder Bicep. Infrastructuur alleen uitwerpen wanneer u de gegenereerde IaC-bestanden rechtstreeks moet beheren.

Verwante inhoud

• Quickstart: Uw eerste gehoste agent implementeren
• azure.yaml maken voor gehoste agents
• naslaginformatie over azure.yaml voor gehoste agents
• Gehoste agentinfrastructuur met de Azure Developer CLI