microsoft/autogen · error · ValueError

Instructions not initialized

Error message

Instructions not initialized

What it means

AzureAIAgent.instructions raises ValueError when _instructions is falsy — the system prompt / instructions were never supplied or are an empty string. The property assumes instructions exist; an agent without them fails on read.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/agents/azure/_azure_ai_agent.py:395

            raise ValueError("Description not initialized")
        return self._description

    @property
    def agent_id(self) -> str:
        if not self._agent_id:
            raise ValueError("Agent not initialized")
        return self._agent_id

    @property
    def deployment_name(self) -> str:
        if not self._deployment_name:
            raise ValueError("Deployment name not initialized")
        return self._deployment_name

    @property
    def instructions(self) -> str:
        if not self._instructions:
            raise ValueError("Instructions not initialized")
        return self._instructions

    @property
    def tools(self) -> List[ToolDefinition]:
        """
        Get the list of tools available to the agent.

        Returns:
            List[ToolDefinition]: The list of tool definitions.
        """
        return self._api_tools

    def _add_tools(self, tools: Optional[ListToolType], converted_tools: List[ToolDefinition]) -> None:
        """
        Convert various tool formats to Azure AI Agent tool definitions.

        Args:
            tools: List of tools in various formats (string identifiers, ToolDefinition objects, Tool objects, or callables)

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Pass non-empty instructions at construction.
2. If instructions are genuinely optional in your app, read via try/except and use a default prompt.
3. Validate rendered instruction templates are non-empty before creating the agent.

Example fix

# before
agent = AzureAIAgent(client, name="a")
print(agent.instructions)  # ValueError
# after
agent = AzureAIAgent(client, name="a", instructions="You are a helpful assistant.")
print(agent.instructions)

instructions = template.render(vars).strip()
assert instructions, "instructions template rendered empty"
agent = AzureAIAgent(client, name="a", instructions=instructions)

try:
    ins = agent.instructions
except ValueError:
    ins = DEFAULT_PROMPT

When it happens

Trigger: Constructing AzureAIAgent with instructions=None or "" and reading agent.instructions.

Common situations: Optional-instruction agents where the caller skips the parameter; templating code producing an empty string when a template var is unset.

Related errors

• Description not initialized
• Deployment name not initialized
• Unsupported tool string: {tool}
• BING_API_KEY environment variable is not set
• Please set AZURE_OPENAI_API_KEY environment variable.

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/31aa0dc1013ebc67. Report an issue: GitHub.