Implementation:Microsoft Agent framework Agent Run

Property	Value
Implementation Name	Agent Run
SDK	Microsoft Agent Framework
Repository	Microsoft Agent Framework
Source File	`python/packages/core/agent_framework/_agents.py`
Line Range	L827-868
Import	`from agent_framework import Agent`
Type	Async instance method

Overview

The Agent.run() method is the primary entry point for executing an agent in the Microsoft Agent Framework. It accepts user messages, processes them through the LLM with automatic tool invocation, and returns either a complete AgentResponse or a ResponseStream for real-time token streaming. The method supports multi-turn conversations via AgentThread and per-call overrides for tools and options.

Code Reference

Source Location

Property	Value
File	`python/packages/core/agent_framework/_agents.py`
Class	`Agent`
Method	`run`
Lines	827-868

Signature

async def run(
    self,
    messages: str | Message | Sequence[str | Message] = ...,
    *,
    stream: bool = False,
    thread: AgentThread | None = None,
    tools: list[FunctionTool | Callable[..., Any]] | None = None,
    options: OptionsCoT | None = None,
) -> AgentResponse | ResponseStream[AgentResponseUpdate, AgentResponse]:

Import Statement

from agent_framework import Agent

I/O Contract

Inputs

Parameter	Type	Default	Description
`messages`	Message \| Sequence[str \| Message]	`...`	The user input to send to the agent. A plain string is treated as a single user message. A `Message` object or a sequence of strings and `Message` objects provides full control over the conversation input.
`stream`	`bool`	`False`	When `True`, returns a `ResponseStream` that yields incremental `AgentResponseUpdate` objects as the LLM generates tokens. When `False` (default), returns a complete `AgentResponse`.
`thread`	None	`None`	An optional thread object for multi-turn conversations. When provided, the conversation history is preserved across successive `run()` calls, enabling the agent to reference prior exchanges.
`tools`	Callable[..., Any]] \| None	`None`	An optional list of tools to make available for this invocation, overriding the agent's default tool set. Accepts both `FunctionTool` instances and plain callables.
`options`	None	`None`	Optional configuration overrides for this invocation, such as chain-of-thought settings or model parameters. Overrides the agent's default options for this call only.

Output

Condition	Type	Description
`stream=False` (default)	`AgentResponse`	A complete response object with the following key attributes: `.text` - The agent's text response as a string. `.messages` - The full list of messages exchanged during execution. `.value` - A structured output value, if the agent is configured to produce one.
`stream=True`	`ResponseStream[AgentResponseUpdate, AgentResponse]`	An asynchronous iterator yielding `AgentResponseUpdate` objects. Each update exposes: `.text` - The incremental text content generated so far. The stream resolves to a final `AgentResponse` upon completion.

Execution Flow

The run() method implements the following sequence:

Input Normalization: The messages parameter is normalized into a list of Message objects. A plain string is wrapped as a single user message.
Thread Attachment: If a thread is provided, the conversation history from the thread is prepended to the message list.
Tool Resolution: If tools is provided, it overrides the agent's default tools for this invocation. Tool schemas are assembled for the LLM.
LLM Invocation: The assembled messages, tool schemas, and options are sent to the LLM.
Tool Invocation Loop: If the LLM response includes tool calls, the agent automatically executes the requested tools, appends the results to the conversation, and re-invokes the LLM. This loop continues until the LLM produces a final text response.
Response Construction: The final response is packaged into an AgentResponse (or streamed as AgentResponseUpdate objects).
Thread Update: If a thread was provided, the new messages are appended to the thread for future turns.

Usage Examples

Non-Streaming Invocation

from agent_framework import Agent

agent = Agent(...)
response = await agent.run("What is the weather?")
print(response.text)

Streaming Invocation

from agent_framework import Agent

agent = Agent(...)
async for update in agent.run("Tell me a story", stream=True):
    print(update.text, end="")

Multi-Turn Conversation with Thread

from agent_framework import Agent, AgentThread

agent = Agent(...)
thread = AgentThread()
r1 = await agent.run("Hello", thread=thread)
r2 = await agent.run("Follow up", thread=thread)

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment