Configure and manage agents in Visual Studio Code

Once you have a declarative agent (created in the Foundry portal or through the SDK), the real work begins — configuring its behavior, instructions, and properties to match your requirements. The Microsoft Foundry VS Code extension provides comprehensive configuration options through both the visual Agent Designer and direct YAML file editing, giving you flexibility in how you work.

Configuring agent properties

The Agent Designer provides an intuitive interface for setting up your agent's core properties. These settings define fundamental aspects of how your agent behaves and performs.

Essential configuration options

In the Agent Designer, you configure several key properties:

Agent name - Enter a descriptive name that clearly identifies your agent's purpose. This name appears in lists, logs, and when other developers work with your agents.

Model selection - Choose your model deployment from the dropdown. This selection determines which AI model powers your agent's responses. The dropdown shows only models you've already deployed in your project.

Description - Add a clear, concise description of what your agent does. Good descriptions help team members understand the agent's purpose without reading its instructions or code.

System instructions - Define the agent's behavior, personality, and response style. This is where you shape how your agent understands its role and interacts with users.

Agent ID - Automatically generated by the extension when you create the agent. This unique identifier is used when calling your agent through APIs.

Model configuration options

Beyond selecting a model, you can fine-tune its behavior through additional parameters:

Temperature - Controls response creativity and randomness. Lower values (0.1-0.3) produce consistent, focused outputs. Higher values (0.7-1.0) generate more creative, varied responses. For business agents handling structured tasks, values between 0.3 and 0.7 typically work well.

Top P - Controls diversity by limiting vocabulary choices during generation. Most scenarios work well with the default value of 1.0, but you can lower it for more constrained, predictable outputs.

These settings appear in both the Designer interface and the YAML file, remaining synchronized across both views.

Understanding the agent YAML structure

The YAML file contains all your declarative agent's configuration in a structured, readable format. Understanding this structure helps you make precise changes and work efficiently when the visual interface isn't the best fit.

Complete YAML example

Here's a fully configured agent YAML file:

# yaml-language-server: $schema=https://aka.ms/ai-foundry-vsc/agent/1.0.0
version: 1.0.0
name: healthcare-assistant
description: Assists healthcare staff with patient appointment scheduling and information retrieval
id: 'agent-abc123xyz'
metadata:
  authors:
    - developer-name
  tags:
    - healthcare
    - customer-service
    - scheduling
model:
  id: 'gpt-4.1'
  options:
    temperature: 0.5
    top_p: 1
instructions: |
  You're a healthcare assistant helping staff schedule patient appointments and retrieve information.
  
  Your responsibilities:
  - Help staff find available appointment slots
  - Answer questions about patient scheduling policies
  - Provide information about different appointment types
  - Assist with rescheduling and cancellations
  
  Important guidelines:
  - Never access or share patient medical information
  - Always verify appointment details before confirming
  - Be professional but friendly in all interactions
  - If you're unsure about policies, advise staff to check with management
tools: []

The YAML structure divides naturally into sections: metadata, model configuration, instructions, and tools. This organization makes it easy to locate and modify specific settings.

Benefits of YAML configuration

Direct YAML editing provides several advantages:

• Version control - Track changes in Git alongside your application code
• Bulk updates - Make multiple changes simultaneously with confidence
• Templates - Create reusable agent templates for consistent configurations
• Code review - Include agent configurations in your standard code review processes
• Automation - Build scripts that generate or modify agent configurations programmatically

The extension validates YAML syntax in real-time, highlighting errors and providing suggestions as you type.

Best practices for agent configuration

As you build more complex agents, these practices help maintain quality and reliability:

Version control your YAML files - Commit agent configurations to Git alongside your application code. This enables rollback, code review, and change tracking.

Use descriptive names and tags - Clear naming and tagging make it easy to find and identify agents as your collection grows.

Document complex instructions - Include comments in your YAML files explaining why you chose specific instruction patterns or configurations.

Test after every change - Use the integrated playground to verify behavior after modifying configuration. Small changes can have unexpected effects.

Start simple, then iterate - Begin with basic instructions and add complexity based on testing results. Overly complex initial instructions are harder to debug.

Keep instructions focused - Each agent should have a clear, specific purpose. Agents trying to do too many things perform inconsistently.

Configuring agents in Visual Studio Code provides powerful capabilities for creating sophisticated automation. The combination of visual design tools and direct YAML editing enables rapid development while maintaining the precision needed for production deployments.