How can we set agent id prior to creation through YAML File? Is it practically possible to set our own agent id?

Deepankar 390 Reputation points
2026-06-19T15:39:33.0266667+00:00

Link for reference: https://learn.microsoft.com/en-us/training/modules/develop-ai-agents-azure-vs-code/6-configure-manage-agents?pivots=text

I was reviewing the Manage Agents learning material and encountered some confusion:

  1. Agent ID generation
    • My understanding is that the Agent ID is automatically generated on the Azure AI Foundry portal once an agent is created.
    • If that’s the case, how can we pre‑define the Agent ID in a YAML file when following the code‑first approach?
  2. Issue faced
    • When the Agent ID is not specified, I attempted a logic check: csharp 
           if (agentId exists)
    proceed with code logic; else create new agent and proceed; 
         
   - The challenge is that on the **first run**, the application creates a new agent. Then, we hardcode the generated Agent ID and use it in subsequent runs to prevent duplicate agents.
  3. Request for guidance
    • Could someone explain the standard procedure for creating an agent through the code‑first approach?
    • Specifically, how can we ensure that on subsequent runs of the application, the same agent is reused and no duplicate agent is created?
    • I would appreciate an explanation or example in C#.

User's image

Foundry Tools
Foundry Tools

Formerly known as Azure AI Services or Azure Cognitive Services is a unified collection of prebuilt AI capabilities within the Microsoft Foundry platform

Answer accepted by question author
Karnam Venkata Rajeswari 5,255 Reputation points Microsoft External Staff Moderator
2026-07-05T13:03:42.5166667+00:00

Hello @Deepankar ,

Welcome to Microsoft Q&A .Thank you for reaching out to us.

 The behavior is expected because Azure AI Foundry separates the agent configuration from the service-generated agent resource identity. The YAML/code-first definition is used to describe the agent’s behavior and configuration, while the Agent ID is generated by the service when the agent resource is created

The right approach is not to predefine the Agent ID, but to make the application’s create/reuse logic idempotent.

  1. Agent definition vs. Agent ID n the code-first flow, the YAML or SDK definition should be treated as the agent specification. It defines what the agent should be configured with, such as:
    • Agent name
    • Model
    • Instructions
    • Tools
    • Additional configuration or metadata
    The Agent ID, however, is a service-generated resource identifier returned after creation. The documented .NET CreateAgentAsync() API accepts creation inputs such as model, optional name, description, and instructions, but it does not expose a parameter for supplying a custom Agent ID during creation. This indicates that the Agent ID is returned by the service rather than authored by the user at create time. YAML / SDK definition = input configuration Agent ID = output generated by Foundry after creation
  2. Agent ID vs. managed agent identity It is also useful to separate the Agent ID from the security identity used by the platform.
    • Agent ID: Resource identifier used to reference the created agent.
    • Agent identity / Microsoft Entra identity: Security identity used for authentication and authorization when the agent accesses tools or other resources.
    For hosted agents, Foundry automatically creates the dedicated Microsoft Entra agent identity and endpoint during deployment. Therefore, this identity should also be treated as platform-managed rather than manually controlled from YAML or application code.

Regarding the a custom Agent ID be predefined in YAML - No documented workflow currently supports predefining a custom Agent ID in YAML or passing a custom Agent ID during agent creation.

The YAML definition should be used to define the agent configuration. The Agent ID should be captured after creation and reused for future operations. In other words, the YAML file should not be used as a mechanism to reserve or assign a specific Agent ID.

The suggested code-first pattern is:

  1. Define a stable logical agent name in YAML or configuration.
  2. Create the agent using the SDK or deployment workflow.
  3. Capture the generated Agent ID returned by the service.
  4. Persist the generated Agent ID in durable configuration.
  5. On later executions, reuse the stored Agent ID.
  6. If the stored ID is missing or stale, attempt to find the existing agent using the stable logical name.
  7. Create a new agent only if no existing reusable agent can be found.

Durable storage options can include:

  • Azure App Configuration
  • Azure Key Vault-backed configuration
  • Database
  • Environment-specific application settings

Azure App Configuration is suitable for centralizing agent-related settings such as endpoint, agent name, model configuration, instructions and YAML-based agent specifications.

To avoid duplicate agents

  1. Read stored Agent ID from configuration at startup
  2. If the stored Agent ID is valid, reuse the existing agent
  3. If the stored Agent ID is missing or stale, search for an existing agent using a stable logical name
  4. If a matching agent is found, reuse it and refresh the stored Agent ID
  5. If no existing agent is found, create a new agent and persist the newly generated Agent ID for future use

If the application can run in parallel, it is recommended to add synchronization around the create step, because two concurrent startup flows could otherwise both check for an agent and then both attempt creation before either one persists the generated ID.

Multi-environment ,like for Dev/Test/Prod deployments, use separate logical names and separate stored Agent IDs per environment.

invoice-triage-agent-dev

invoice-triage-agent-test

invoice-triage-agent-prod

Each environment should maintain its own generated Agent ID in that environment’s configuration store. This avoids accidental reuse across environments and keeps deployments predictable.

The following references might be helpful , please check them out

Thank you

 

Please "Accept" the answer with an "Upvote" if the response was helpful. This will be benefitting other community members who face the same issue.

Was this answer helpful?

1 person found this answer helpful.
0 comments

1 additional answer

Sort by: Most helpful
Most helpful Newest Oldest

  1. AI answer

    2026-06-19T15:39:54.3666667+00:00

    Agent IDs in Azure AI Foundry are generated and managed by the platform. The designer in Visual Studio Code explicitly states that the Id value is generated by the extension when creating an agent:

    “The extension generates the Id value.”

    This means:

    • The id field in the agent YAML is not meant to be a user‑chosen identifier for the backing service resource.
    • The actual agent identity (for authentication and authorization) is handled separately by the Microsoft Entra Agent ID platform and, for Foundry projects, is automatically provisioned and managed:

    “Microsoft Foundry automatically provisions and manages agent identities throughout the agent lifecycle. When the first agent in a Foundry project is created, Microsoft Foundry provisions a default agent identity blueprint and a default agent identity for the project… Publishing an agent automatically creates a dedicated agent identity blueprint and agent identity…”

    Because of this automatic provisioning, there is no supported mechanism in the provided documentation to:

    • Pre‑set a custom Agent ID value before creation, or
    • Control the underlying Entra Agent ID directly via the YAML.

    Instead, the standard pattern is:

    1. Define the agent (name, model, instructions, tools) in YAML or via the designer.
    2. Let the toolkit/portal generate the agent’s id and the corresponding Entra agent identity.
    3. Persist and reuse that generated id (for example, in configuration or App Configuration) when wiring up application code.

    The context does not provide a C# sample for a “create‑if‑not‑exists” pattern against the Foundry agent service, nor any API that allows specifying a custom ID at creation time. It only shows how to load an existing YAML specification (for example, from Azure App Configuration) and create an agent object in code from that spec.

    Given the available information, the supported approach is to treat the agent id as an opaque, system‑assigned identifier and store it for reuse, rather than trying to define or control it ahead of time.

    References:

    AI-generated content may be incorrect. Read our transparency notes for more information.

    Was this answer helpful?

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.