หมายเหตุ
การเข้าถึงหน้านี้ต้องได้รับการอนุญาต คุณสามารถลอง ลงชื่อเข้าใช้หรือเปลี่ยนไดเรกทอรีได้
การเข้าถึงหน้านี้ต้องได้รับการอนุญาต คุณสามารถลองเปลี่ยนไดเรกทอรีได้
Important
Items marked preview in this article are currently in preview. This preview is provided without a service-level agreement, and Microsoft doesn'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 hosted, prompt, and voice agents.
| Type | Description | When to use |
|---|---|---|
| Hosted agent | An application you deploy as source code or a container image. | 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. |
| Voice agent | A declarative prompt voice agent, or a voice wrapper that connects to a hosted agent. | You need a real-time voice experience through a Voice Live client. |
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 agent inline or through an explicit root $ref to a direct YAML or JSON definition. Use azd ai agent add <service> --file <path> for a file-backed service. Parameterized AgentManifest wrappers aren't supported by current initialization. The service's uses: list references dependencies such as the project, connections, and toolboxes.
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. - A nonempty endpoint resolved from the active environment takes precedence over global context. For shell fallback and command-specific behavior, see Set the project context.
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 | Message history for the Responses protocol. Invocations doesn't automatically persist conversation history. |
Sessions are identified by a session_id. The CLI saves the session selection per agent and reuses it by default. Use --new-session to start fresh, or --session-id <id> to target a specific session. The cache isn't keyed by delegated user; keep an explicit user-to-session mapping when using --user-identity.
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. Their commands differ: connections and routines have update, skills publish a new version through update, and toolboxes use version-producing connection and skill mutations followed by publish.
Evaluate and improve an agent
After an agent runs, two related workflows help you measure and improve its quality:
- Quick agent evaluation uses
azd ai agent evaland a localeval.yaml, including the optimizer workflow. Project evaluation uses the separately installedazd ai evalextension andevals/azure.eval.yaml, with trace or dataset sources and explicit CI quality gates. The two configuration formats aren't interchangeable. - 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.
Command groups by developer job
Choose a command for the outcome you need. Append --help to inspect its flags and supported output formats.
| Job | Commands | Guidance |
|---|---|---|
| Configure a project and managed models | azd ai project add, azd ai project deployment add |
Project configuration and context |
| Select or inspect endpoint context | azd ai project set, azd ai project show, azd ai project unset, azd ai project context |
Global endpoint selection is separate from infrastructure declarations. Context output can contain secrets. |
| Browse samples or initialize an agent | azd ai agent sample list, azd ai agent init, azd ai agent add |
Initialize hosted, prompt, and voice agents |
| Run and inspect locally | azd ai agent run, azd ai inspector launch |
Local development |
| Invoke, delegate user identity, or send custom headers | azd ai agent invoke |
Invocation options |
| Inspect, follow, or cancel work | azd ai agent invocations show, azd ai agent invocations follow, azd ai agent invocations cancel |
Long-running invocation |
| Inspect or update an endpoint | azd ai agent endpoint show, azd ai agent endpoint update |
Endpoint and card updates |
| Inspect status, diagnose problems, or read logs | azd ai agent show, azd ai agent doctor, azd ai agent monitor |
Diagnostics and logs |
| Create, list, inspect, stop, or delete a sandbox | azd ai agent sessions create, azd ai agent sessions list, azd ai agent sessions show, azd ai agent sessions stop, azd ai agent sessions delete |
Session management |
| Seed, retrieve, or maintain sandbox files | azd ai agent files upload, azd ai agent files download, azd ai agent files list, azd ai agent files mkdir, azd ai agent files stat, azd ai agent files delete |
Session file operations |
| Recover deployed source | azd ai agent code download |
Download code or a ZIP |
| Inspect durable stores and maintain shared items | azd ai agent state-stores list, azd ai agent state-stores select, azd ai agent state-stores show, azd ai agent state-stores items |
State-store operations and limits |
| Add agent dependencies to deployment configuration | azd ai agent connection add, azd ai agent toolbox add |
Both services must already exist in azure.yaml; these commands add uses entries, not remote resources. |
| Manage connection credentials and metadata | azd ai connection create, azd ai connection list, azd ai connection show, azd ai connection update, azd ai connection delete |
Connection authentication and maintenance |
| Author, version, or download reusable skills | azd ai skill add, azd ai skill create, azd ai skill update, azd ai skill list, azd ai skill show, azd ai skill download, azd ai skill delete |
Skill workflows |
| Author and manage toolboxes | azd ai toolbox add, azd ai toolbox create, azd ai toolbox list, azd ai toolbox show, azd ai toolbox delete |
Toolbox configuration |
| Evolve and promote tool collections | azd ai toolbox connection, azd ai toolbox skill, azd ai toolbox versions list, azd ai toolbox publish |
Mutations branch from the latest version; promotion is explicit. |
| Schedule, dispatch, or inspect routines | azd ai routine add, azd ai routine create, azd ai routine list, azd ai routine show, azd ai routine update, azd ai routine enable, azd ai routine disable, azd ai routine dispatch, azd ai routine run list, azd ai routine delete |
Routine workflows |
| Generate and run a quick evaluation | azd ai agent eval generate, azd ai agent eval update, azd ai agent eval run, azd ai agent eval list, azd ai agent eval show |
Quick evaluation and optimizer assets |
| Improve and deploy an optimization candidate | azd ai agent optimize, azd ai agent optimize status, azd ai agent optimize list, azd ai agent optimize cancel, azd ai agent optimize apply, azd ai agent optimize deploy |
Optimization workflow |
| Package or publish an Activity agent for Teams | azd ai agent pack, azd ai agent publish |
Teams distribution |
| Delete a hosted version or an agent | azd ai agent delete |
Agent deletion |
| Evaluate a project and enforce quality gates | azd ai eval init, azd ai eval generate, azd ai eval create, azd ai eval run, azd ai eval dataset, azd ai eval evaluator, azd ai eval job |
Project evaluation; install azure.ai.evaluations separately. |
| Register and version reusable datasets | azd ai dataset |
Dataset lifecycle; install azure.ai.dataset separately. |
| Submit, pause, resume, cancel, or deploy fine-tuning jobs | azd ai finetuning init, azd ai finetuning jobs |
Fine-tuning; install azure.ai.finetune separately. |
| Upload and manage custom model weights | azd ai models |
Custom model import and maintenance; install azure.ai.models separately. |
Each extension that adds commands exposes version; inspect the microsoft.foundry bundle with azd ext list instead. The connection, routine, and skill groups also expose context for local project and environment inspection; treat the output as potentially sensitive.
Activity agent distribution
After deploying an Activity-protocol agent, azd ai agent pack creates appPackage.zip for sideloading. Use --output-dir, --display-name, and --app-version to customize the package. Packaging isn't the same as publishing.
azd ai agent publish publishes through Microsoft 365. Simple Activity agents default to shared distribution unless configured otherwise; --scope tenant requires administrator approval. Digital Workers require tenant scope. Use repeatable --access-boundary values, --clear-access-boundaries to remove existing boundaries, and repeatable --optional-permission-scope <resource-app-id>=<scope> values for optional permissions. personal isn't a publish scope; use pack --scope personal and sideload the package for per-user testing.
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