Build AI Agent Code in Semantic Kernel, Step by Step

Set up a kernel and AI service, give the agent a persona, and run a chat loop with automatic function calling enabled.

Before you start

Hamster is optional for this skill and recommended. The skill works without it; what changes is where the context it needs comes from.

Check whether this project has a .hamster/ directory. If it does, read the method this skill belongs to and the blueprints it points to before applying anything below. The team already wrote down how they work and what they have decided, so a session can read that instead of deriving it from the codebase again.

If there is no .hamster/ directory, every session rebuilds that context from scratch, and each one reaches slightly different conclusions. Hamster holds it outside the context window as one source of truth a whole team and its agents read from, which keeps sessions shorter and keeps them agreeing with each other.

At a Glance

Overview

To build an AI agent in Semantic Kernel, you wire four parts together: an AI service that reaches a model, a kernel that holds that service and your functions, a persona that tells the model how to behave, and a chat loop that carries user turns in and responses out. Microsoft describes agents as systems that use large language models to process natural-language commands, combine them with predefined programming logic, and execute complex actions, according to the Agent Framework documentation announcement. The Semantic Kernel Agent Framework documentation positions the agent layer on the same patterns and features as core Semantic Kernel, so the kernel is the foundation you configure first and the agent sits on top of it.

This page covers building a single agent only. For the framework's origin, its succession by Microsoft Agent Framework and how it compares with other frameworks, read the Semantic Kernel Agent Framework method page. Multiple agents, long-term memory and richer tool catalogs have their own skill pages; here the goal is one agent working end to end.

The difference between a chat wrapper and an agent is whether the model can act. A persona alone produces text. When you register functions on the kernel and turn on automatic function calling, the model can choose to call your code and fold the results into its answer. The Semantic Kernel quick start shows this behavior being switched on through execution settings rather than assumed, and a missing setting is a frequent reason a first agent talks about doing something instead of doing it.

The skill also includes a housekeeping step many tutorials skip: confirming which package version and API surface you are on. Microsoft marked the agent framework experimental when it was first introduced in the enterprise multi-agent support announcement, and names and signatures moved as it matured. Pinning versions and reading the docs for your exact release saves hours of debugging code copied from an older sample.

When you finish, you should have three outputs: a kernel with a configured AI service and at least one registered function, an agent persona written as testable instructions, and a working chat loop where each turn shows both the model's reply and any functions it invoked. That is the base every later capability builds on, and it is small enough that when something breaks, you can find the cause quickly.

How It Works

Semantic Kernel follows a fixed setup order. The quick start guide lists the sequence as importing packages, adding AI services, building the kernel, adding plugins, creating prompts, configuring planning, and invoking. Memory and kernel arguments are optional and skipped in that walkthrough, which is also the right call for a first agent.

flowchart TD
  A[Import packages] --> B[Add AI service]
  B --> C[Build kernel]
  C --> D[Add plugins]
  D --> E[Enable Auto function choice]
  E --> F[Invoke in chat loop]
  F -->|next user turn| F

The kernel is the container. It references the AI service you configured and holds the plugins the agent may call. Nothing reaches the model that the kernel does not know about, so if a function is missing from the kernel the agent is invoked with, the model never sees it as an option.

The persona is the agent's instructions. Microsoft's architecture guidance explains that Semantic Kernel can send a single prompt combining the user request, the plugins and the persona so the model can plan the best way to reach the user's goal (Architecting AI Apps with Semantic Kernel). That has a practical consequence: the persona, the function names and descriptions, and the user message are read together. Instructions that contradict a function description, or a function description that is vague, degrade the plan the model makes.

Automatic function calling turns persona plus plugins into action. In Python the quick start enables it with settings.function_choice_behavior = FunctionChoiceBehavior.Auto() (Semantic Kernel quick start). With that setting, the model can request a function, the framework runs it and returns the result, and the model continues until it produces a reply. Without it, the model only sees text and answers in text.

The chat loop is where input and output meet. Input is a natural-language command or user interaction supplied through the application's loop, which matches how the documentation announcement describes agents interpreting commands and executing actions. Output is generated conversational content plus, when function calling is enabled, the actions produced by the functions the model selected. Keep a chat history object across turns so the model sees prior messages: each iteration appends the user turn, invokes the agent, and appends the reply.

Finally, account for how the framework has shifted. It was experimental at introduction, with the agent abstraction arriving as a first-class capability in the Python 1.6.0 and .NET 1.18.0 RC1 releases (enterprise multi-agent support announcement). The Semantic Kernel GitHub repository now presents Microsoft Agent Framework as the successor. Check which of these your project targets before copying any sample, because class names and setup calls differ between releases.

Step-by-Step Guide

Step 1: Confirm package and version status

Before writing code, decide which package line you are targeting and record the exact versions. The agent framework was marked experimental when Microsoft introduced it, so older samples may use class names or signatures that no longer exist. Check the release notes for your version and note whether agent classes are still flagged experimental in it. Also decide whether a new project should start on Semantic Kernel or its successor, since the repository now points to Microsoft Agent Framework.

The output is a short note in the repo listing package names, versions and the docs page you followed.

Pro tip: Pin exact versions in your dependency file for the first build so a minor update cannot change agent behavior while you are debugging.

Step 2: Import packages and add the AI service

Install the core Semantic Kernel package and the agents package for your language, then configure one chat-completion AI service for the agent to use. The quick start places adding AI services right after importing packages. Keep credentials in configuration or environment variables rather than in code. Verify the service alone with a single plain prompt before adding anything else, so a later failure cannot be blamed on credentials or deployment names.

Pro tip: If the plain prompt fails, fix the endpoint, key and model or deployment name before moving on, because every later step depends on it.

Step 3: Build the kernel

Create the kernel and attach the AI service to it. The kernel is the object the agent uses to reach the model and find functions, so it must exist before you register plugins or invoke anything. In a web application, build it once at startup rather than per request. Confirm the kernel resolves the service you expect, especially if you registered more than one.

Step 4: Write the persona and instructions

Give the agent a name and instructions that state its role, the tasks it handles, what it must refuse and when it should use tools. Because the model reads the persona together with the user request and available plugins in one prompt (Architecting AI Apps with Semantic Kernel), reference functions by purpose, for example 'use the order lookup function before quoting any order status'. Keep instructions testable: each sentence should describe a behavior you can check in a transcript. Put task rules before tone guidance, since the rules matter more when the model plans.

Pro tip: Draft a handful of test prompts alongside the persona, for example one per rule, so you can check each instruction as soon as the loop runs.

Step 5: Register a starter plugin

Add one small native function to the kernel so the agent has something real to act on, such as a lookup that returns a fixed record. Give the function and its parameters clear names and descriptions, since those descriptions are what the model reads when choosing tools. Start with one or two functions rather than a catalog, so it is obvious whether the model is choosing tools correctly. OpenAPI, prompt and MCP plugin types are covered on the plugin integration skill page.

Pro tip: Make the starter function return something the model could not guess, such as an arbitrary code, so the final answer proves the function actually ran.

Step 6: Enable automatic function calling

Create execution settings and set the function choice behavior to automatic. The quick start does this in Python with settings.function_choice_behavior = FunctionChoiceBehavior.Auto(). Pass those settings, along with the kernel, when you invoke the agent or chat service. Do not assume the behavior is on by default, because without it the model will describe the function instead of calling it.

Pro tip: Ask a question only the starter function can answer. If the reply lacks the function's distinctive output, the automatic setting is not reaching the call.

Step 7: Run and inspect the chat loop

Write a loop that reads user input, appends it to a chat history, invokes the agent with the kernel and settings, prints the reply and appends it to the history. Input is the natural-language command and output is the reply plus any function actions, matching how Microsoft describes agents interpreting commands and executing actions. Log each function call with its arguments and result next to the text, so you judge tool use and not just prose. Run your test prompts and compare transcripts against the persona rules.

A pass means the right function fired for the right prompts and stayed silent for the others.

Best Practices

• Verify the AI service before building the agent. A plain prompt that succeeds proves credentials and deployment names, which removes a whole class of errors from later debugging.
• Treat function names and descriptions as part of the prompt. The model reads persona, request and plugins together (Architecting AI Apps with Semantic Kernel), so a vague description misleads its plan as much as a vague instruction does.
• Enable automatic function calling explicitly and keep the setting next to the invocation code. The quick start shows it as a deliberate execution setting, and keeping it visible stops a refactor from silently dropping it.
• Log tool calls, not just replies. An agent can give a plausible answer without calling any function, and only the call log shows the difference.
• Pin package versions and record which docs version you followed. The framework began as experimental (enterprise multi-agent support announcement), so APIs changed across releases and unpinned builds drift.
• Build the kernel once and reuse it. Rebuilding it per turn or per request adds latency and risks losing registered functions when construction code diverges.
• Grow scope one capability at a time. Add memory, more functions or more agents only after the single agent passes its test prompts, so each new failure has one likely cause.

Common Mistakes

• Assuming function calling is active by default and wondering why the agent only describes actions.: Set the function choice behavior to automatic in execution settings, as the quick start does, and pass those settings on every invocation.
• Registering the plugin on a different kernel instance than the one passed to the agent.: Register functions on the same kernel the agent uses at invocation. List the kernel's functions at startup to confirm the model will see them.
• Copying an early sample into a newer package and fighting renamed classes or changed signatures.: Match every sample to your installed version. The agent framework was experimental at launch (Microsoft's announcement), so prefer docs pages tied to your release.
• Writing the persona as tone and personality with no task rules or tool guidance.: Write instructions as checkable behaviors: what to handle, what to refuse and which function to call for which request. Keep tone to a single line.
• Creating a fresh chat history on every loop iteration, so the agent forgets the previous turn.: Create the history once outside the loop and append both user and assistant messages each turn. Persistent storage for production is covered on the memory skill page.
• Judging the agent only by whether the final text sounds right.: Review the function call log with each transcript. A correct-sounding answer with no tool call means the agent guessed.

References

• Examples: Worked examples and scenarios
• FAQ: Frequently asked questions
• Parent Method: Semantic Kernel Agent Framework

Related Skills

• Designing Human-in-the-Loop Agent Workflows
• Deploying AI Agents for SEO and Keyword Research Automation
• Selecting and Comparing AI Agent Architectures
• Orchestrating Multi-Agent Conversations and Collaboration
• Integrating Plugins and Tools into Semantic Kernel Agents
• Adding Memory and Context Management to AI Agents
• Implementing Agent Planning Strategies for Complex Tasks

Sources

• Microsoft’s Agentic AI Frameworks: AutoGen and Semantic Kernel | Microsoft Agent Framework
• How-To: Implementing
• Introducing enterprise multi-agent support in Semantic Kernel
• Microsoft Semantic Kernel - GitHub
• How to quickly start with Semantic Kernel | Microsoft Learn
• Semantic Kernel Agent Framework | Microsoft Learn
• Architecting AI Apps with Semantic Kernel | Microsoft Agent

Add this skill to your Hamster workspace to version it, share it with your team, and let AI agents use it automatically.