Python: How do I use OpenAPI plugins (with API keys) in Semantic Kernel Python?

[spasegirl]

I’m experimenting with the [Semantic Kernel Python SDK] and trying to use an OpenAPI plugin (for OpenWeatherMap) both for manual function calls and with an agent (like AzureAIAgent).
I’m running into some confusion about how to supply the required API key (appid) when calling these functions, especially when the agent is supposed to handle things.

What I tried:

I loaded my OpenAPI spec using kernel.add_plugin_from_openapi(...) and I can see the functions loaded under kernel.plugins["weather"].

I can see the function, e.g., getCurrentWeather, but when I try await kernel.plugins["weather"]["getCurrentWeather"].invoke(...), I get errors (or the LLM doesn’t pass the key, so the API returns 401 Unauthorized).

When I use an agent and just type “What’s the weather in Hamburg?” the LLM/agent may try to call the tool, but it fails without the key, or it just asks me for the key.

My questions:

What is the correct way to call an OpenAPI function directly in Python SK? (The docs mention .invoke and .invoke_async, but the API surface seems to have changed.)

Is there a way to configure SK Python so that the agent or LLM always supplies my API key to the OpenAPI function call, so it just works for end users? (Like with environment variables, config, or a built-in hook?)

Is there a minimal, modern example that shows how to use OpenAPI plugins with agents, with authentication?

Any code snippets or pointers are super appreciated!
If you need my OpenAPI spec or code, I can provide it.

Thank you! 🙏

weather_openapi_spec.json

[moonbox3]

Hi @spasegirl, you brought up two different ways of interacting with an OpenAPI spec: SK's ChatCompletionAgent or AzureAIAgent.

For the ChatCompletion agent, as you said, you'll add the plugin via kernel.add_plugin_from_openapi(...). To add auth, you'll want to leverage the OpenAPIFunctionExecutionParameters auth_callback attribute. You can do something like:

import os

from semantic_kernel import Kernel
from semantic_kernel.connectors.openapi_plugin import (
    OpenAPIFunctionExecutionParameters,
)
from semantic_kernel.functions import KernelArguments


OPENWEATHER_KEY = os.getenv("OPENWEATHER_KEY")  # or whatever you have it called

async def add_openweather_key(**_) -> dict[str, str]:
    # This could also be {"Authorization": "Bearer <key>"} or whatever other header you need
    return {"x-api-key": OPENWEATHER_KEY}

You'll then do something like:

kernel.add_plugin_from_openapi(
    plugin_name="weather",
    openapi_document_path="openweather.yaml",
    execution_settings=OpenAPIFunctionExecutionParameters(
        auth_callback=add_openweather_key,
        server_url_override="https://api.openweathermap.org",  # if required
    ),
)

You can then call it directly:

result = await kernel.invoke(
    plugin_name="weather",
    function_name="getCurrentWeather",
    arguments=KernelArguments(lat=1.234, lon=1.234),
)
print(result)

If you provide the kernel instance to a ChatCompletionAgent, it can leverage it during function calling. If it doesn't have the required information to call the function, it will ask the user for it, and then call the function to get the weather. The auth callback will still be used as part of function execution.

from semantic_kernel.agents import ChatCompletionAgent, ChatHistoryAgentThread
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion

agent = ChatCompletionAgent(
    service=AzureChatCompletion(),
    name="WeatherAgent",
    instructions="Answer questions about the weather.",
    kernel=kernel,  # has weather plugin already defined
)

For the other agent type - AzureAIAgent, they have a different style of using an OpenAPI tool. Our getting start sample shows a non-auth scenario. You'll want to switch out this Anonymous auth for something like OpenApiConnectionAuthDetails or OpenApiManagedAuthDetails. They have docs showing how to use OpenAPI auth here.

[moonbox3]

Hi @spasegirl, hopefully this gets you unblocked. If you continue to experience issues, please either re-open this issue or create a new one. Thanks.