> ## Documentation Index
> Fetch the complete documentation index at: https://hobbyist-e43fa225.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent development with the Azure Developer CLI
> Understand the end-to-end developer workflow for building, deploying, and operating hosted agents on Microsoft Foundry with the Azure Developer CLI.
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](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
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 hosted agent on Microsoft Foundry. 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](/developer-tools-and-integrations/install-cli-sdk) |
| Scaffold | Initialize a project from a template or your existing code. | [Quickstart: Deploy a hosted agent](/agents/quickstart-hosted-agent) |
| Define | Configure the agent, model deployment dependencies, protocols, tools, and environment in `azure.yaml`. | [Author azure.yaml for hosted agents](/agents/author-azure-yaml) |
| Develop | Write agent logic, add tools, and test locally. | [Tools overview](/get-started/tool-catalog) |
| Deploy | Provision infrastructure and deploy to Foundry. | [Deploy a hosted agent](/agents/deploy-hosted-agent) |
| Operate | Monitor logs, manage versions, and automate runs. | [Manage hosted agents](/agents/manage-hosted-agent) |
| Evaluate | Measure agent quality and improve the prompt. | [Run agent evaluations with the azd CLI](/evaluation/azure-developer-cli-evaluation) |
## Agent types
The `azd ai agent` extension focuses on hosted agents.
| 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. |
Hosted agents give you full control over the runtime, framework, and tool integrations, while Foundry handles infrastructure, scaling, and session management.
## 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.
### Variable substitution
Use `${VAR_NAME}` in `azure.yaml` for values that differ by `azd` environment. The placeholder resolves from `.azure//.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 `azd` project, commands resolve the Foundry project endpoint from the active `azd` environment.
* Outside an `azd` project, set the active context once with `azd ai project set `, or pass `--project-endpoint` on an individual resource command (`connection`, `toolbox`, `skill`, or `routine`). As a fallback, `azd ai` reads the `FOUNDRY_PROJECT_ENDPOINT` environment 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](/agents/hosted-agent-contract).
## 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 ` 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](/evaluation/azure-developer-cli-evaluation) and [Optimize agent prompts](/agents/prompt-optimizer).
## Deployment lifecycle
The full developer loop condenses into a short sequence of commands. Scaffold once, then use the direct commands as your project grows.
```bash theme={null}
# 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
```
## Related content
* [Quickstart: Deploy your first hosted agent](/agents/quickstart-hosted-agent)
* [What are hosted agents?](/agents/hosted-agents)
* [Hosted agent runtime contract](/agents/hosted-agent-contract)
* [Agent development lifecycle](/agents/development-lifecycle)