Prerequisites
Before getting started, ensure you have:- A SambaCloud account and API key.
- Python 3.10 or later. Run
python --versionto confirm. Semantic Kernel 1.0 and later requires Python 3.10, and on Python 3.9pipinstalls the incompatible 0.9 beta instead.
Installation and setup
-
Create a virtual environment.
If
python --versionreports 3.9 or earlier, create the environment with an explicit interpreter instead, for examplepython3.11 -m venv .venv. -
Install the required libraries.
The upper bound keeps you on the 1.x agent API. Semantic Kernel changed the
ChatCompletionAgentconstructor between 0.9 and 1.0, so pin the major version and test before you upgrade. -
Create a
.envfile in the same directory and add your credentials. SambaCloud exposes an OpenAI-compatible endpoint, so Semantic Kernel connects to it through the standard OpenAI connector.Leave the unused IDs empty.OpenAIChatCompletionreads these variables at construction time, so the notebook fails at the first agent call if they are missing. Pass any SambaCloud model asOPENAI_CHAT_MODEL_ID. Agent workflows that give agents tools also need a model that supports function calling.
Example notebook
Follow along with the Semantic Kernel example notebook to create agents that can function as art directors and copywriters, helping automate creative tasks with advanced AI capabilities.If the first agent cell fails with
TypeError: ChatCompletionAgent.__init__() got an unexpected keyword argument 'service_id', apply the one-line fix in Troubleshooting. The pinned 1.x API no longer accepts service_id on the agent constructor.If you open the notebook in an editor such as VS Code instead, select the interpreter inside
.venv before you run any cells. Selecting an interpreter does not restart an already-running kernel, so restart the kernel afterward. To confirm which interpreter is actually attached, run import sys, os; print(sys.executable, os.environ.get("VIRTUAL_ENV")) in a cell. A VIRTUAL_ENV of None means the kernel is running outside the environment.Troubleshooting
ImportError: cannot import name 'Url' from 'pydantic.networks'
ImportError: cannot import name 'Url' from 'pydantic.networks'
You installed the 0.9 beta, which is the last release that supports Python 3.9. On Python 3.9,
pip selects it silently because 1.0 and later require Python 3.10.Confirm python --version is 3.10 or later, then recreate the environment and reinstall with the bounded command in Installation and setup. Upgrading in place does not help, because no 1.x release installs on Python 3.9.TypeError: ChatCompletionAgent.init() got an unexpected keyword argument 'service_id'
TypeError: ChatCompletionAgent.init() got an unexpected keyword argument 'service_id'
ChatCompletionAgent accepted service_id in 0.9. In 1.0 and later, the agent takes a configured kernel or service instead.Remove the service_id argument from the agent constructor. Keep it on OpenAIChatCompletion, which still accepts it.ModuleNotFoundError: No module named 'semantic_kernel' in a notebook
ModuleNotFoundError: No module named 'semantic_kernel' in a notebook
The notebook kernel is running outside your virtual environment, usually because the editor started it from a different interpreter.Restart the kernel after selecting the environment, then verify with the check in the note above. Launching
jupyter lab from the activated environment avoids the problem entirely.401 from the endpoint
401 from the endpoint
OPENAI_API_KEY is unset, expired, or the .env file is not in the directory the notebook runs from.Confirm the key works with a completion request:200 confirms the key is valid. Test against a completion request rather than a model listing, because the models endpoint answers without checking credentials.