Notă
Accesul la această pagină necesită autorizare. Puteți încerca să vă conectați sau să modificați directoarele.
Accesul la această pagină necesită autorizare. Puteți încerca să modificați directoarele.
Important
Items marked (preview) in this article are currently in public preview. This preview is provided without a service-level agreement, and we don't recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.
The Azure Developer CLI (azd) and its azd ai agent extension give you a single command-line workflow to go from idea to a production-ready agent on Microsoft Foundry. You can develop code-based hosted agents and declarative prompt-based voice agents. This article explains the developer journey, the files that define an agent, and the core concepts you encounter along the way.
This article is for developers who prefer a terminal-first, scriptable workflow over the Foundry portal or language SDKs.
The developer journey
The azd ai workflow follows the same lifecycle whether you build a small prototype or a production agent. You scaffold a project once, then mix and match commands as your project grows.
| Stage | What you do | Where to learn more |
|---|---|---|
| Install | Install azd and the Foundry extensions. |
Set up your developer environment |
| Scaffold | Initialize a hosted agent from a template or your existing code, or create a prompt-based voice agent. | Quickstart: Deploy a hosted agent or Quickstart: Create a prompt voice agent |
| Define | Configure the agent, model deployment dependencies, protocols, tools, and environment in azure.yaml. |
Author azure.yaml for hosted agents |
| Develop | Write agent logic, add tools using a toolbox, and test locally. | Toolbox overview |
| Deploy | Provision infrastructure and deploy to Foundry. | Deploy a hosted agent |
| Operate | Monitor logs, manage versions, and automate runs. | Manage hosted agents |
| Evaluate | Measure agent quality and improve the prompt. | Run agent evaluations with the azd CLI |
Agent types
The azd ai agent extension supports code-based and declarative agent types.
| Type | Description | When to use |
|---|---|---|
| Hosted agent | A containerized application you build in code, package as a Docker image, and deploy to Foundry. | You need custom logic, framework integration, or full control over behavior. |
| Prompt agent | An agent defined entirely through instructions and tool configurations, with no custom code. | You want a quick, config-driven agent without writing application code. |
| Prompt-based voice agent | A declarative voice agent that uses a managed or self-deployed model without custom runtime code. | You want a real-time conversational voice experience without building and hosting an audio pipeline. |
| Hosted voice agent with a managed wrapper | A hosted target handles conversation logic, while a separate voice service delegates to it through conversationEngine. Voice Live handles the audio experience. |
You need custom agent logic without implementing speech recognition and synthesis in the hosted target. |
Hosted agents give you full control over the runtime, framework, and tool integrations, while Foundry handles infrastructure, scaling, and session management.
Prompt-based voice agents don't require a custom container. If you need to run
a custom speech-to-speech or cascaded audio pipeline in your own container,
build a voice agent with a hosted agent and
use the invocations_ws protocol.
To keep conversation logic in a hosted text agent while Voice Live handles audio, use the hosted voice wrapper workflow. The wrapper and target are separate services in the same azure.yaml project. This flow doesn't replace the existing custom invocations_ws audio-pipeline flow.
Before using the public-preview voice CLI options, check your installed extension as described in the voice agent quickstart prerequisites.
Configuration files
A hosted agent project uses one azure.yaml file at the project root to declare both the agent and its provisioning and deployment model. The file uses a split-service model, where each named service has a host value such as azure.ai.project, azure.ai.agent, azure.ai.connection, azure.ai.toolbox, azure.ai.skill, or azure.ai.routine.
| File | Purpose | Who maintains it |
|---|---|---|
azure.yaml |
Declares the Foundry project, model deployments, hosted agent service, dependencies, protocols, tools, environment variables, container resources, and deployment settings. Agent identity, model, protocols, tools, and environment values live in the azure.ai.agent service. |
Initialization generates it. You customize it as needed. |
The azure.ai.agent service defines your hosted agent inline and uses uses: to reference other services, such as the project, connections, toolboxes, skills, and routines. There is no standalone agent.yaml or agent.manifest.yaml file in the current hosted-agent azd project model.
For a prompt-based voice agent, azure.yaml stores the declarative agent
definition, including kind: prompt-voice, the model, the model type, and the
agent name. It doesn't include a hosted-agent container runtime. To customize
instructions, audio, turn detection, transcription, voice output, tools, and
greetings, see
Configure a voice agent.
For a hosted voice wrapper, conversationEngine.name references the hosted target's service name. The wrapper's uses dependency orders deployment, and conversationEngine.version defaults to the version deployed by the current environment. See the voice service reference for the configuration fields.
Variable substitution
Use ${VAR_NAME} in azure.yaml for values that differ by azd environment. The placeholder resolves from .azure/<env>/.env at deploy or run time, so the same azure.yaml works across environments such as dev, staging, and production.
Where the CLI runs
The azd ai commands work both inside and outside an azd project directory:
- Inside an
azdproject, commands resolve the Foundry project endpoint from the activeazdenvironment. - Outside an
azdproject, set the active context once withazd ai project set <endpoint>, or pass--project-endpointon an individual resource command (connection,toolbox,skill, orroutine). As a fallback,azd aireads theFOUNDRY_PROJECT_ENDPOINTenvironment variable. - An in-project environment always takes precedence over the global context, so changing directories into a project retargets the CLI at that project's endpoint.
Protocols
A protocol defines the HTTP contract between Foundry and your agent container. Your agent listens on port 8088 and serves a health probe, regardless of protocol.
| Protocol | API style | When to use |
|---|---|---|
responses |
OpenAI Responses API (POST /responses) |
The standard choice, compatible with the OpenAI API ecosystem. |
invocations |
Custom JSON contract (POST /invocations) |
When you need full control over request and response payloads. |
For the full specification, see Hosted agent runtime contract.
These protocol settings apply to hosted-agent containers. Prompt-based voice agents don't configure a hosted-agent protocol.
azd ai agent invoke doesn't implement voice conversations for prompt-based voice agents or hosted voice wrappers. For the CLI behavior and testing guidance, see Voice agent limitations.
Sessions and conversations
| Concept | Description |
|---|---|
| Session | An isolated execution environment for a single agent interaction. Each session runs in its own sandbox with dedicated resources. |
| Conversation | A sequence of messages within a session. Foundry manages conversation history and can hydrate it across requests. |
Sessions are identified by a session_id. When you run azd ai agent invoke, Foundry reuses the session from your last invocation by default. Use --new-session to start fresh, or --session-id <id> to target a specific session.
Resources on a Foundry project
A Foundry project hosts more than agents. It also holds shared resources that agents reference at runtime. The CLI manages each one through a dedicated command group.
| Resource | What it is | Managed with |
|---|---|---|
| Connection | Links a Foundry project to an external resource, such as an MCP server, Azure AI Search, or Grounding with Bing. | azd ai connection commands |
| Toolbox | A named collection of tools that agents use at runtime. | azd ai toolbox commands |
| Skill | A reusable behavioral guideline shared across agents on the project. | azd ai skill commands |
| Routine | A trigger plus an action that invokes an agent. | azd ai routine commands |
These resources are shared across developers and agents on the same project. Each command group exposes the standard create, update, delete, show, and list verbs.
Evaluate and improve an agent
After an agent runs, two related workflows help you measure and improve its quality:
- Evaluation runs your agent against a dataset, scores the responses with one or more evaluators, and reports an aggregate quality signal. You manage it with
azd ai agent eval. - Optimization iteratively rewrites your agent's prompt to lift an evaluation signal. It uses an evaluation as its objective function and produces a candidate prompt that you review and accept. You manage it with
azd ai agent optimize.
For details, see Run agent evaluations with the azd CLI and Optimize agent prompts.
Deployment lifecycle
The full developer loop condenses into a short sequence of commands. Scaffold once, then use the direct commands as your project grows.
For the managed voice-agent path, see Quickstart: Create a prompt voice agent.
# Scaffold a project from a template or your existing code
azd ai agent init
# Run locally and invoke
azd ai agent run
azd ai agent invoke --local "Hello, world!"
# Provision infrastructure and deploy the agent
azd up
# Extend the project with shared resources at any time
azd ai connection create my-search --kind cognitive-search --target https://... --auth-type api-key --key "..."
azd ai routine create daily-digest --trigger recurring --cron "0 7 * * *" --agent-name my-agent
# Evaluate quality
azd ai agent eval generate
azd ai agent eval run
# Tear down all Azure resources
azd down