Skip to content

feat(ai-agents): add managed harness prompt agents - #9805

Draft
Zhijie Huang (hund030) wants to merge 12 commits into
mainfrom
feature/managed-harness-agents
Draft

feat(ai-agents): add managed harness prompt agents#9805
Zhijie Huang (hund030) wants to merge 12 commits into
mainfrom
feature/managed-harness-agents

Conversation

@hund030

@hund030 Zhijie Huang (hund030) commented Sep 1, 2026

Copy link
Copy Markdown
Contributor

Summary

Add prompt agents and optional github_copilot_preview managed harness support to the Foundry agent lifecycle, using portable project configuration and service-authoritative capability validation.

Changes

  • azd ai agent init: scaffold kind: prompt agents, optionally configure a managed harness, and bind an existing or provisioned Foundry project.
  • Agent lifecycle: support prompt-agent deployment through azd deploy, plus filtered list, show, invoke, and delete flows.
  • Prompt definitions: map models, instructions, tools, skills, memory, connections, and RAI policies while retaining structural validation and deferring evolving harness support rules to Foundry.
  • Foundry provisioning: resolve portable project endpoints consistently for greenfield and existing-project environments.

CLI Interface

# Plain prompt agent
azd ai agent init --kind prompt --agent-name my-agent --model gpt-5-mini --instructions "Be helpful."

# Managed harness prompt agent
azd ai agent init --kind prompt --harness github_copilot_preview --agent-name my-agent --model gpt-5-mini --instructions "Be helpful."

The generated azure.yaml agent service can also carry richer prompt configuration:

services:
  my-agent:
    host: azure.ai.agent
    kind: prompt
    name: my-agent
    model: gpt-5-mini
    instructions: Be helpful.
    harness:
      type: github_copilot_preview
    skills:
      - summarize
    tools:
      - type: azure_ai_search
        azure_ai_search:
          index_name: docs
    policies:
      - type: rai_policy
        raiPolicyName: ${RAI_POLICY_ID}

Use --project-id <resource-id> --model-deployment <name> to initialize against an existing Foundry project and deployment. Standard lifecycle commands are azd up, azd deploy, and azd ai agent show|list|invoke|delete.

Manual Validation

  • Initialized a managed prompt-agent project and successfully provisioned it against an existing Foundry project.
  • Deployed and invoked a basic managed agent against an enabled test subscription, receiving the expected response marker.
  • Confirmed through live REST calls that non-strict function, File Search, Azure AI Search, Fabric IQ, and Work IQ tools are accepted; File Search and Azure AI Search reached runtime execution.

…9754)

* feat(ai-agents): agent.yaml model and Foundry service clients

First of four stacked changes adding managed harness agent support.
This one is the data model and the HTTP clients; it adds no commands
and performs no deployment, so it can be read on its own.

agent_yaml gains the prompt agent manifest: the harness block and its
skills, environment and built-in tool controls, the memory block, tool
declarations, and the feature gate that decides which manifest features
a given harness accepts. Blocks azd interprets reject unknown keys, so
a typo such as builtin_tool for builtin_tools fails the parse instead of
deploying an agent with capabilities the author believed were off. Tools
stay untyped and pass through, so a tool newer than this build still
deploys.

agent_api gains the managed agent contract and its operations. pkg/azure
gains the Foundry data plane clients for files, projects, connections
and RAI policies; the toolsets client is removed because the service
replaced it with the connections control plane.

New spelling terms stay in the extension cspell config rather than the
shared core one, which this branch does not touch.

* fix(ai-agents): preserve inline RAI policy fields

* refactor(ai-agents): reuse unified prompt agent client

* refactor(ai-agents): reference supported sibling resources

---------

Co-authored-by: hund030 <zhihuan@microsoft.com>
* feat(ai-agents): agent.yaml model and Foundry service clients

First of four stacked changes adding managed harness agent support.
This one is the data model and the HTTP clients; it adds no commands
and performs no deployment, so it can be read on its own.

agent_yaml gains the prompt agent manifest: the harness block and its
skills, environment and built-in tool controls, the memory block, tool
declarations, and the feature gate that decides which manifest features
a given harness accepts. Blocks azd interprets reject unknown keys, so
a typo such as builtin_tool for builtin_tools fails the parse instead of
deploying an agent with capabilities the author believed were off. Tools
stay untyped and pass through, so a tool newer than this build still
deploys.

agent_api gains the managed agent contract and its operations. pkg/azure
gains the Foundry data plane clients for files, projects, connections
and RAI policies; the toolsets client is removed because the service
replaced it with the connections control plane.

New spelling terms stay in the extension cspell config rather than the
shared core one, which this branch does not touch.

* feat(ai-agents): provision and deploy prompt agents

Second of four stacked changes. Builds on the model and clients from the
previous change and adds the service target that turns a prompt agent
manifest into deployed Foundry resources.

Deployment is graph driven. The manifest is resolved into nodes for the
agent and for every resource it depends on -- memory store, connections,
skills, RAI policy -- and the graph decides creation order and reports
per node progress. Sibling resources are reconciled rather than
recreated, so a redeploy that changes nothing makes no writes.

This package is submitted whole rather than split further. The graph
types are shared by every node implementation and the nodes are
mutually referential, so any smaller cut does not compile without a
refactor that would itself need review.

* fix(ai-agents): preserve inline RAI policy fields

* refactor(ai-agents): reuse unified prompt agent client

* refactor(ai-agents): reference supported sibling resources

* refactor(ai-agents): align prompt deployment dependencies

* fix(ai-agents): constrain prompt deployment to Foundry

* fix(ai-agents): scope prompt deployment state

* fix(ai-agents): bypass tagged lookup for prompt agents

* fix(ai-agents): align prompt schema and policy contract

* fix(ai-agents): remove unshipped prompt config fallback

---------

Co-authored-by: hund030 <zhihuan@microsoft.com>
* feat(ai-agents): agent.yaml model and Foundry service clients

First of four stacked changes adding managed harness agent support.
This one is the data model and the HTTP clients; it adds no commands
and performs no deployment, so it can be read on its own.

agent_yaml gains the prompt agent manifest: the harness block and its
skills, environment and built-in tool controls, the memory block, tool
declarations, and the feature gate that decides which manifest features
a given harness accepts. Blocks azd interprets reject unknown keys, so
a typo such as builtin_tool for builtin_tools fails the parse instead of
deploying an agent with capabilities the author believed were off. Tools
stay untyped and pass through, so a tool newer than this build still
deploys.

agent_api gains the managed agent contract and its operations. pkg/azure
gains the Foundry data plane clients for files, projects, connections
and RAI policies; the toolsets client is removed because the service
replaced it with the connections control plane.

New spelling terms stay in the extension cspell config rather than the
shared core one, which this branch does not touch.

* feat(ai-agents): provision and deploy prompt agents

Second of four stacked changes. Builds on the model and clients from the
previous change and adds the service target that turns a prompt agent
manifest into deployed Foundry resources.

Deployment is graph driven. The manifest is resolved into nodes for the
agent and for every resource it depends on -- memory store, connections,
skills, RAI policy -- and the graph decides creation order and reports
per node progress. Sibling resources are reconciled rather than
recreated, so a redeploy that changes nothing makes no writes.

This package is submitted whole rather than split further. The graph
types are shared by every node implementation and the nodes are
mutually referential, so any smaller cut does not compile without a
refactor that would itself need review.

* feat(ai-agents): CLI surface for managed harness agents

Third of four stacked changes. Adds the commands that sit on top of the
model and the deployment engine from the previous two.

azd ai agent init gains a kind and harness selection and writes the
matching manifest, including discovery of an existing Responsible AI
policy with a warn and fall back path when none can be read. list, show,
delete and invoke gain managed agent handling, with invoke supporting
streamed responses. Infrastructure synthesis learns the project endpoint
so a generated module resolves it from the environment.

Also carries the extension CHANGELOG for all four changes in this stack,
since the entries describe features that only exist once the stack is
complete.

* fix(ai-agents): preserve inline RAI policy fields

* refactor(ai-agents): reuse unified prompt agent client

* refactor(ai-agents): reference supported sibling resources

* refactor(ai-agents): align prompt deployment dependencies

* fix(ai-agents): constrain prompt deployment to Foundry

* fix(ai-agents): scope prompt deployment state

* fix(ai-agents): align prompt CLI with Foundry

* fix(ai-agents): enforce managed prompt CLI contract

* fix(ai-agents): unify prompt project context

* fix(ai-agents): bypass tagged lookup for prompt agents

* fix(ai-agents): complete managed prompt invocation

* fix(ai-agents): finalize prompt init contract

* fix(ai-agents): finalize prompt agent lifecycle

---------

Co-authored-by: hund030 <zhihuan@microsoft.com>
…ss-agents

# Conflicts:
#	cli/azd/extensions/azure.ai.agents/internal/cmd/init_infra.go
#	cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_yaml/yaml.go
#	cli/azd/extensions/azure.ai.agents/internal/pkg/azure/foundry_toolsets_client.go
#	cli/azd/extensions/azure.ai.agents/internal/pkg/azure/foundry_toolsets_client_test.go
#	cli/azd/extensions/azure.ai.agents/schemas/azure.ai.agent.json
@azure-pipelines

Copy link
Copy Markdown
Azure Pipelines:
Successfully started running 4 pipeline(s).
23 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds first-class prompt agents and optional managed harness support to the Foundry agent lifecycle.

Changes:

  • Adds prompt-agent configuration, initialization, and schema support.
  • Implements deployment dependencies and lifecycle commands.
  • Adds portable Foundry endpoint resolution for new and existing projects.

Reviewed changes

Copilot reviewed 100 out of 100 changed files in this pull request and generated 10 comments.

Show a summary per file
File Description
cli/azd/extensions/azure.ai.agents/README.md Updates RAI policy guidance.
cli/azd/extensions/azure.ai.agents/cspell.yaml Adds extension terminology.
cli/azd/extensions/azure.ai.agents/internal/exterrors/codes.go Updates extension error codes.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_api/models.go Models prompt-agent API data.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_api/operations.go Extends agent API operations.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_api/responses_operations.go Implements Responses API calls.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_api/responses_operations_test.go Tests Responses API behavior.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_yaml/managed_test.go Tests managed-agent mapping.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_yaml/map.go Maps prompt definitions to API requests.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_yaml/parse.go Validates prompt manifests.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_yaml/prompt_features.go Validates prompt features and policies.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_yaml/prompt_features_test.go Tests prompt feature validation.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_yaml/prompt_harness_gate.go Validates harness configuration.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_yaml/prompt_harness_gate_test.go Tests harness validation.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_yaml/prompt_schema_test.go Tests prompt schema behavior.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_yaml/prompt_strict_inline.go Strictly validates inline blocks.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_yaml/prompt_strict_yaml_test.go Tests strict YAML decoding.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_yaml/prompt_tools.go Validates prompt tool definitions.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_yaml/prompt_tools_test.go Tests prompt tool handling.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_yaml/yaml.go Defines prompt-agent YAML models.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_yaml/yaml_test.go Tests YAML model behavior.
cli/azd/extensions/azure.ai.agents/internal/pkg/azure/foundry_rai_policies.go Adds Foundry RAI policy access.
cli/azd/extensions/azure.ai.agents/internal/pkg/azure/foundry_rai_policies_test.go Tests RAI policy utilities.
cli/azd/extensions/azure.ai.agents/schemas/azure.ai.agent.json Extends the public agent schema.
cli/azd/extensions/azure.ai.agents/internal/project/agent_definition.go Resolves prompt definitions.
cli/azd/extensions/azure.ai.agents/internal/project/agent_definition_ref_test.go Tests definition references.
cli/azd/extensions/azure.ai.agents/internal/project/agent_definition_test.go Tests definition loading.
cli/azd/extensions/azure.ai.agents/internal/project/agent_policies_test.go Tests inline policy preservation.
cli/azd/extensions/azure.ai.agents/internal/project/config.go Adds prompt service configuration.
cli/azd/extensions/azure.ai.agents/internal/project/doc_examples_test.go Validates documented examples.
cli/azd/extensions/azure.ai.agents/internal/project/foundry_dependencies.go Extends Foundry dependency checks.
cli/azd/extensions/azure.ai.agents/internal/project/memory_store.go Shares memory-store reconciliation.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_client.go Configures prompt API clients.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_client_test.go Tests prompt client settings.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_connections.go Resolves connection dependencies.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_connections_test.go Tests connection resolution.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_convention_test.go Tests prompt file conventions.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_deployment.go Resolves model deployment nodes.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_deployment_test.go Tests deployment nodes.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_environment_test.go Tests deployment environment outputs.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_graph.go Builds the deployment graph.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_graph_warnings_test.go Tests deployment warnings.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_headers_test.go Tests request headers.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_inline.go Decodes inline prompt definitions.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_inline_test.go Tests inline definitions.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_json_schema_test.go Tests schema integration.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_memory.go Provisions prompt memory stores.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_memory_test.go Tests memory provisioning.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_policy_node.go Verifies RAI policy dependencies.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_policy_node_test.go Tests policy dependency handling.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_skills.go Resolves skills and toolboxes.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_skills_test.go Tests skills and toolboxes.
cli/azd/extensions/azure.ai.agents/internal/project/prompt_tools_test.go Tests prompt tool deployment.
cli/azd/extensions/azure.ai.agents/internal/project/service_target_agent.go Dispatches prompt service targets.
cli/azd/extensions/azure.ai.agents/internal/project/service_target_agent_test.go Tests service-target initialization.
cli/azd/extensions/azure.ai.agents/internal/project/service_target_prompt.go Implements prompt deployment.
cli/azd/extensions/azure.ai.agents/internal/cmd/agent_endpoint.go Resolves prompt endpoints.
cli/azd/extensions/azure.ai.agents/internal/cmd/delete.go Adds prompt-agent deletion.
cli/azd/extensions/azure.ai.agents/internal/cmd/doctor/checks_agent_status.go Extends status diagnostics.
cli/azd/extensions/azure.ai.agents/internal/cmd/helpers.go Supports prompt service resolution.
cli/azd/extensions/azure.ai.agents/internal/cmd/init.go Routes prompt initialization.
cli/azd/extensions/azure.ai.agents/internal/cmd/init_adopt.go Integrates prompt adoption.
cli/azd/extensions/azure.ai.agents/internal/cmd/init_adopt_test.go Tests adoption behavior.
cli/azd/extensions/azure.ai.agents/internal/cmd/init_from_code.go Aligns code initialization.
cli/azd/extensions/azure.ai.agents/internal/cmd/init_from_templates_helpers.go Adds template helpers.
cli/azd/extensions/azure.ai.agents/internal/cmd/init_from_templates_helpers_test.go Tests template helpers.
cli/azd/extensions/azure.ai.agents/internal/cmd/init_infra.go Integrates Foundry infrastructure.
cli/azd/extensions/azure.ai.agents/internal/cmd/init_managed.go Scaffolds prompt agents.
cli/azd/extensions/azure.ai.agents/internal/cmd/init_managed_flags_test.go Tests managed flags.
cli/azd/extensions/azure.ai.agents/internal/cmd/init_managed_foundry.go Resolves Foundry targets and models.
cli/azd/extensions/azure.ai.agents/internal/cmd/init_managed_manifest_test.go Tests manifest-based initialization.
cli/azd/extensions/azure.ai.agents/internal/cmd/init_managed_test.go Tests prompt initialization.
cli/azd/extensions/azure.ai.agents/internal/cmd/init_rai_policy.go Adds RAI policy selection.
cli/azd/extensions/azure.ai.agents/internal/cmd/init_rai_policy_test.go Tests policy selection.
cli/azd/extensions/azure.ai.agents/internal/cmd/init_test.go Extends init coverage.
cli/azd/extensions/azure.ai.agents/internal/cmd/invoke.go Routes prompt invocation.
cli/azd/extensions/azure.ai.agents/internal/cmd/invoke_managed.go Streams prompt responses.
cli/azd/extensions/azure.ai.agents/internal/cmd/invoke_managed_stream_test.go Tests SSE streaming.
cli/azd/extensions/azure.ai.agents/internal/cmd/invoke_managed_test.go Tests prompt invocation.
cli/azd/extensions/azure.ai.agents/internal/cmd/list.go Lists prompt agents.
cli/azd/extensions/azure.ai.agents/internal/cmd/list_prompt_test.go Tests prompt listing.
cli/azd/extensions/azure.ai.agents/internal/cmd/listen.go Adds prompt cleanup hooks.
cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/error_codes.go Updates next-step errors.
cli/azd/extensions/azure.ai.agents/internal/cmd/project_endpoint.go Validates Foundry endpoints.
cli/azd/extensions/azure.ai.agents/internal/cmd/project_endpoint_test.go Tests endpoint validation.
cli/azd/extensions/azure.ai.agents/internal/cmd/prompt_service.go Resolves prompt service context.
cli/azd/extensions/azure.ai.agents/internal/cmd/prompt_service_test.go Tests prompt service resolution.
cli/azd/extensions/azure.ai.agents/internal/cmd/resource_services.go Emits Foundry sibling services.
cli/azd/extensions/azure.ai.agents/internal/cmd/resource_services_test.go Tests sibling service emission.
cli/azd/extensions/azure.ai.agents/internal/cmd/root.go Registers the list command.
cli/azd/extensions/azure.ai.agents/internal/cmd/show.go Adds prompt-agent status output.
cli/azd/extensions/azure.ai.agents/internal/cmd/show_test.go Tests prompt status output.
cli/azd/extensions/azure.ai.agents/internal/synthesis/synthesizer.go Expands portable project endpoints.
cli/azd/extensions/azure.ai.agents/internal/synthesis/synthesizer_test.go Tests endpoint expansion.
cli/azd/extensions/azure.ai.projects/internal/provisioning/foundry_provisioning_provider.go Resolves portable provisioning targets.
cli/azd/extensions/azure.ai.projects/internal/provisioning/foundry_provisioning_provider_test.go Tests resolved project endpoints.
cli/azd/extensions/azure.ai.projects/internal/provisioning/resource_group_location_check.go Handles portable brownfield endpoints.
cli/azd/extensions/azure.ai.projects/internal/provisioning/resource_group_location_check_validate_test.go Tests location-check routing.
cli/azd/extensions/azure.ai.projects/internal/synthesis/synthesizer.go Mirrors endpoint expansion logic.
cli/azd/extensions/azure.ai.projects/internal/synthesis/synthesizer_test.go Updates synthesis endpoint tests.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.


switch {
case requestedKind == AgentKindChoicePrompt:
harness, harnessErr := resolveInitHarness(flags.harness, "")
Comment on lines +324 to +328
promptAgent.Skills = manifest.definition.Skills
promptAgent.Tools = manifest.definition.Tools
promptAgent.ToolChoice = manifest.definition.ToolChoice
promptAgent.StructuredInputs = manifest.definition.StructuredInputs
promptAgent.Policies = manifest.definition.Policies
Comment on lines 205 to 208
projectCfg, err := project.MarshalStruct(&project.ServiceTargetAgentConfig{
Endpoint: projectEndpoint,
Deployments: deployments,
Deployments: resources.Deployments,
})
Comment on lines +81 to +83
if !runtime.HasStatusCode(resp, http.StatusOK, http.StatusCreated, http.StatusAccepted) {
return nil, nil, runtime.NewResponseError(resp)
}
Comment on lines +25 to +27
for entry := range strings.SplitSeq(env["AZURE_AI_PROJECT_CONNECTION_NAMES"], ",") {
if strings.EqualFold(strings.TrimSpace(entry), strings.TrimSpace(name)) {
return true
Comment on lines +44 to +45
if strings.HasPrefix(trimmed, raiPolicyIDPrefix) && strings.Contains(trimmed, raiPolicyIDSegment) {
return nil
return err
}

list, err := client.ListAgents(ctx, promptListQuery(), pctx.Settings.EffectiveAPIVersion())
"properties": {
"promptAgent": {
"type": "object",
"description": "Marks the service as a Prompt-family (prompt, prompt-voice, managed) agent and tells azd how to reach the harness that runs it. `azd ai agent init` writes every field as a ${VAR} reference so azure.yaml carries no tenant-specific values.",
},
"$ref": {
"type": "string",
"description": "Path to the file carrying this agent's definition, relative to the service's project directory. Defaults to agent.yaml when omitted."
Comment on lines +193 to +195
policy, it only associates the agent with an existing one. For prompt and
managed agents, `azd ai agent init` lists the policies on the selected account
and can bind one for you; see `--rai-policy`.
@github-actions github-actions Bot added the ext-projects azure.ai.projects extension label Sep 2, 2026
@azure-sdk-automation

Copy link
Copy Markdown
Contributor

azure.ai.agents PR build

Note

This is an unsigned development build. Install it only if you trust this PR.

Install the extension:

azd ext install "https://azuresdkartifacts.z5.web.core.windows.net/azd/extensions/pr/9805/azure-ai-agents.zip"
  • Version: 1.0.0-beta.13.pr.9805.6777781
  • Merge commit: e14f548

@azure-sdk-automation

Copy link
Copy Markdown
Contributor

azure.ai.projects PR build

Note

This is an unsigned development build. Install it only if you trust this PR.

Install the extension:

azd ext install "https://azuresdkartifacts.z5.web.core.windows.net/azd/extensions/pr/9805/azure-ai-projects.zip"
  • Version: 1.0.0-beta.8.pr.9805.6777782
  • Merge commit: e14f548

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/extensions Extensions (general) ext-agents azure.ai.agents extension ext-projects azure.ai.projects extension

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support prompt and managed harness agents in azd

3 participants