How to Build an AI Agent: Understanding the Two-Layer Architecture

Creating an AI agent can often lead to confusion because many guides mix two distinct roles into one complicated process: the building part and the running part. However, if we separate these roles, constructing an AI agent becomes much clearer.

Two Layers of Agent Development

We can think of modern agent development as a tidy two-layer system. At the top, there’s the Coding Agent, which is responsible for creating the agent. Beneath it lies the Runtime Agent, which actually operates within your business. The Microsoft Agent Framework acts as the software development kit (SDK) that connects these layers, while Microsoft Foundry serves as the platform for both to function.

The Key Ingredient: SKILL

The secret that transforms a standard Copilot into a knowledgeable engineer is the SKILL. This crucial component is what the Coding Agent refers to before it starts coding. It ensures that the agent’s requirements are turned into practical artifacts that align perfectly with your framework, conventions, and fixtures.

Learning the Architecture with ZavaShop

This post will guide you through this two-layer setup, emphasising the importance of SKILL in the first layer. We will use a fictional global e-commerce business, ZavaShop, which operates five fulfillment centres and has a CEO keen on having a live dashboard. You can choose either Python or .NET (C#) for your implementation — whichever suits your team’s production environment better.

Understanding the Coding Agent

It’s essential to clarify that the Coding Agent is not the one your customers interact with. Instead, it’s the creator of the agent that customers do engage with. This agent generates a collection of outputs: code, definitions, workflows, skills, and tests, which are validated and then sent to Foundry.

Build Process Overview

The building process can be broken down into several key steps:

1. Identify a Real Business Challenge: Instead of saying, “Let’s build an agent,” state a specific need, such as “Mei, the supervisor at Seattle DC, is frequently interrupted with stock questions.”
2. Define Acceptance Criteria: Clarify what success looks like. For example, “The agent should respond to stock queries for our 10-SKU catalog with a latency of under 4 seconds and a wrong-tool rate below 5%.”
3. Establish Fixtures: Provide real or realistic data—such as warehouses, SKUs, POs, and customers—so the Coding Agent has a clear context.

Creating the SKILL

The SKILL is a structured file that guides the Coding Agent on writing code according to your specific framework and domain. It contains various essential aspects, such as:

• Purpose: Guidelines on using the SKILL within your specific context.
• Framework Idioms: Instructions for constructing and registering components.
• Code Patterns: Reference snippets that standardize naming and error handling.
• Fixture Contracts: How to load and manage your data fixtures effectively.

Version Control for SKILLS

Your SKILL should be updated alongside your codebase. Whenever new idioms are introduced, a single update to the SKILL ensures every new agent retains consistency across versions.

Transitioning to the Runtime Agent

Once your Coding Agent has produced the necessary artifacts, they’ll flow into Foundry and Azure. This is when the Runtime Agent comes into play, interfacing with users through familiar channels such as Microsoft Teams or a custom web application.

Runtime Agent Functions

The Runtime Agent performs several functions:

• Planning: Determines the next step based on the input.
• Memory Handling: Remembers user interactions and preferences.
• Generating Outputs: This includes writing purchase orders, drafting emails, and more.

Key Takeaways

Remember, building an AI agent involves two distinct phases: the creation phase with the Coding Agent and the operational phase with the Runtime Agent. The Microsoft Framework provides the necessary environment for both to interact seamlessly. The pivotal element in this entire process is the SKILL — once done correctly, it shapes every agent you create afterward, embedding your team’s practices and standards into each one.

FAQs

What is a Coding Agent?

The Coding Agent is responsible for creating the agent’s structure, functions, and overall coding architecture.

Why is SKILL so important?

SKILL connects the coding process to your specific framework, ensuring the output meets your expectations and standards.

How does the Runtime Agent interact with users?

The Runtime Agent communicates via platforms like Microsoft Teams or custom web apps depending on where your users are active.

Can I use different programming languages?

Yes, you can choose between Python or .NET (C#) for your development needs based on your team’s expertise.