microsoft/autogen · error · ValueError

Thread not initialized

Error message

Thread not initialized

What it means

The AzureAIAgent.thread_id property raises ValueError when the underlying Azure AI Projects agent thread has not been created yet. The agent is lazily initialized (_ensure_initialized creates/loads the thread); accessing thread_id before any on_messages/on_messages_stream/save_state call (or before explicit initialization) hits _thread is None.

Source

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

        self._temperature = temperature
        self._tool_resources = tool_resources
        self._top_p = top_p
        self._vector_store_id: Optional[str] = None
        self._uploaded_file_ids: List[str] = []

        self._initial_message_ids: Set[str] = set()
        self._initial_state_retrieved: bool = False

    # Properties
    @property
    def produced_message_types(self) -> Sequence[type[ChatMessage]]:
        """The types of messages that the assistant agent produces."""
        return (TextMessage,)

    @property
    def thread_id(self) -> str:
        if self._thread is None:
            raise ValueError("Thread not initialized")
        return self._thread.id

    @property
    def _get_agent_id(self) -> str:
        if self._agent is None:
            raise ValueError("Agent not initialized")
        return self._agent.id

    @property
    def description(self) -> str:
        if not self._description:
            raise ValueError("Description not initialized")
        return self._description

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

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Trigger initialization first: await any on_messages/on_messages_stream call, or call the agent's initialization path (await agent._ensure_initialized() / perform a first run) before reading thread_id.
2. If you need the id up front, create the thread yourself with the project client and pass it in at construction time (the constructor accepts an existing thread).
3. Wrap the access in try/except ValueError and retry after the first successful run.
4. Check the agent's source version — newer versions expose async initialization; consult the class docstring for the supported way to pre-initialize.

Example fix

# before
agent = AzureAIAgent(client, name="a")
print(agent.thread_id)  # ValueError
# after
await agent.on_messages([TextMessage(content="hi", source="user")], CancellationToken())
print(agent.thread_id)

try:
    tid = agent.thread_id
except ValueError:
    await agent.on_messages([TextMessage(content="init", source="user")], None)
    tid = agent.thread_id

When it happens

Trigger: Constructing AzureAIAgent and reading agent.thread_id immediately, before calling any method that triggers _ensure_initialized; or after on_messages raised early so initialization never completed.

Common situations: Building the agent then immediately logging/associating its thread id; sharing a partially-initialized agent across tasks; an exception during the first run leaving the agent half-initialized.

Related errors

• Agent not initialized
• Description not initialized
• Deployment name not initialized
• Instructions not initialized
• Unsupported tool string: {tool}

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