Agents & prompts
For per-agent presentation settings, see Inline visuals: enable one agent. Presentation settings do not select a host or grant tool/source access.
Microsoft Agent Framework (MAF) provides two application building blocks: an Agent for a conversation and a Workflow for a process with explicit steps, conditions and human input. Hosting and tools are separate choices. Creating a prompt agent in the Foundry portal does not replace the application code, its instructions or its registered tools.
Make three independent choices before deployment: the experience
(conversational, workflow or both), one native host, and optional
capabilities. Reviewed application code composes them; selecting a host does
not automatically enable retrieval or MCP tools.
Before you start
Use the compatible platform manifest and orchestrator source. To change instructions, you need a reviewed source checkout and permission to build and publish its image. To enable a capability, first prepare its source, connection, network path and authorized runtime identity. Start with Agent hosting if the application is not deployed.
Choose the application experience
APPLICATION_MODE selects the experience. The default is conversational.
Use the deployment configuration
to change the selection; this is not a per-message switch.
| Value | Experience |
|---|---|
conversational |
A MAF Agent answers questions and uses authorized tools. |
workflow |
A published MAF Workflow executes a named process and can wait for human input. |
both |
The UI offers conversation and a named process. On Hosted, these are two separate publications. |
ORCHESTRATION_HOST selects hosted or container_apps.
Agent hosting explains the distinct native integrations
and their state ownership. Neither mode selects a retrieval strategy.
The UI presents the task, not a hosting or strategy picker.
Choose capabilities independently
MCP, Foundry IQ and Azure AI Search are tools or retrieval capabilities, not alternative agent implementations. An agent and a workflow can use the same authorized capability when it is registered in their definitions.
- Use Foundry IQ for a knowledge base over native or independently indexed sources.
- Use Tools & MCP for reviewed operations and downstream identity requirements.
- Use Agent App MCP Server for explicitly selected toolsets
on either host. Its default
MCP_TOOLSETS=[]registers zero tools;["nl2sql"]selects the supplied NL2SQL tools, a distinct execution path from a remote Fabric data agent. - Use Document formats & images to distinguish document processing from direct image input in chat.
A source, model or MCP endpoint in configuration does not automatically make that capability available. Its definition, permissions and network path must all be present. Instructions cannot grant document access or turn a retrieval source into a model-callable operation.
Configure instructions
In the orchestrator repository, edit src/native/prompts/main.txt for the
shared agent instructions. src/native/agent.py loads that packaged file.
Both conversation and the workflow's draft step use this definition.
src/native/workflow.py owns the reference graph; src/native/contracts.py
owns its typed inputs, result and registration names.
- Change instructions in the reviewed source, keeping task, grounding, citation and tool-use requirements explicit.
- Test the changed behavior against synthetic inputs and existing native tests. Prompt text cannot grant source access or register new tools.
- Build and publish the reviewed image through Customize components and the matching deployment procedure. A portal prompt edit or App Configuration key does not replace the file.
- Start a new interaction on the new publication/revision. Check a grounded answer, a denied source and required-tool failure before admitting users. Record the image/version with the result.
Graph, executor-ID and registration-name changes also require a compatible publication and a recovery plan for waiting runs. Do not replace their definition while assuming every pending native checkpoint remains compatible.
For a supported functional change such as CHAT_TEMPERATURE or
CHAT_OUTPUT_TOKENS, use the
runtime-setting procedure
under label agent-lz. These are functional values, not packaged instructions.
A running workflow retains its functional configuration snapshot; a new
configuration value does not rewrite a process that is already waiting.
Current authorization is checked separately on every interaction.
Configure and test behavior
- Before provision, select mode and host using Agent hosting. For optional retrieval/tool flags, use the exact agent capability declaration; do not assume a same-named azd environment variable is mapped.
- Keep instructions focused on task, grounding, citations and tool use. Never include user tokens, credentials or private configuration in prompts.
- Test a representative answer, required-source failure, denied user and cancellation. For workflows, also test pending human input, reconnect, rejection and a stale or duplicate reply.
- Follow Customize components and the deployment guide for reviewed source and image deployment.
For process operation, see Workflows & human input. For caller boundaries, see Sign-in & access and the API reference.