Metadata-Version: 2.5
Name: agent-framework-core
Version: 1.25.0
Summary: Microsoft Agent Framework for building AI Agents with Python. This is the core package that has all the core abstractions and implementations.
Author-email: Microsoft <af-support@microsoft.com>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Typing :: Typed
License-File: LICENSE
Requires-Dist: msgspec>=0.20.0,<0.23
Requires-Dist: typing-extensions>=4.15.0,<5
Requires-Dist: pydantic>=2,<3
Requires-Dist: python-dotenv>=1,<2
Requires-Dist: opentelemetry-api>=1.39.0,<2
Requires-Dist: pyyaml>=6.0,<7.0
Requires-Dist: regex>=2024.11.6
Requires-Dist: mcp>=2.2.0,<3 ; extra == "all"
Requires-Dist: tenacity>=9.1.4,<9.2.0 ; extra == "all"
Requires-Dist: agent-framework-a2a>=1.0.0b261106,<2 ; extra == "all"
Requires-Dist: agent-framework-ag-ui>=1.8.0,<2 ; extra == "all"
Requires-Dist: agent-framework-anthropic>=1.0.0b261106,<2 ; extra == "all"
Requires-Dist: agent-framework-azure-ai-search>=1.0.0b261106,<2 ; extra == "all"
Requires-Dist: agent-framework-azure-contentunderstanding>=1.0.0b261106,<2 ; extra == "all"
Requires-Dist: agent-framework-azure-cosmos>=1.0.0b261106,<2 ; extra == "all"
Requires-Dist: agent-framework-azurefunctions>=1.0.0b260922,<2 ; extra == "all"
Requires-Dist: agent-framework-bedrock>=1.0.0b261106,<2 ; extra == "all"
Requires-Dist: agent-framework-chatkit>=1.0.0b261106,<2 ; extra == "all"
Requires-Dist: agent-framework-claude>=1.0.0b261106,<2 ; extra == "all"
Requires-Dist: agent-framework-copilotstudio>=1.0.0b261106,<2 ; extra == "all"
Requires-Dist: agent-framework-declarative>=1.5.0,<2 ; extra == "all"
Requires-Dist: agent-framework-devui>=1.0.0b261106,<2 ; extra == "all"
Requires-Dist: agent-framework-durabletask>=1.0.0b260922,<2 ; extra == "all"
Requires-Dist: agent-framework-foundry>=1.16.1,<2 ; extra == "all"
Requires-Dist: agent-framework-foundry-hosting>=1.0.0b261106,<2 ; extra == "all"
Requires-Dist: agent-framework-foundry-local>=1.0.0b261106,<2 ; extra == "all" and ( python_version >= '3.11' and python_version < '3.15' and ((sys_platform == 'darwin' and platform_machine == 'arm64') or (sys_platform == 'linux' and (platform_machine == 'x86_64' or platform_machine == 'aarch64')) or (sys_platform == 'win32' and (platform_machine == 'AMD64' or platform_machine == 'ARM64' or platform_machine == 'x86_64' or platform_machine == 'aarch64'))))
Requires-Dist: agent-framework-gemini>=1.0.0b261106,<2 ; extra == "all"
Requires-Dist: agent-framework-github-copilot>=2.1.2,<3 ; extra == "all"
Requires-Dist: agent-framework-hyperlight>=1.0.0b261106,<2 ; extra == "all" and ( (sys_platform == 'linux' and platform_machine == 'x86_64') or (sys_platform == 'win32' and platform_machine == 'AMD64'))
Requires-Dist: agent-framework-mem0>=1.0.0b261106,<2 ; extra == "all"
Requires-Dist: agent-framework-mistral>=1.0.0b261106,<2 ; extra == "all"
Requires-Dist: agent-framework-monty>=1.0.0b261106,<2 ; extra == "all"
Requires-Dist: agent-framework-ollama>=1.0.0b261106,<2 ; extra == "all"
Requires-Dist: agent-framework-openai>=1.18.1,<2 ; extra == "all"
Requires-Dist: agent-framework-orchestrations>=1.4.2,<2 ; extra == "all"
Requires-Dist: agent-framework-purview>=1.0.0b261106,<2 ; extra == "all"
Requires-Dist: agent-framework-redis>=1.0.0b261106,<2 ; extra == "all"
Requires-Dist: agent-framework-tools>=1.0.0b261106,<2 ; extra == "all"
Project-URL: homepage, https://aka.ms/agent-framework
Project-URL: issues, https://github.com/microsoft/agent-framework/issues
Project-URL: release_notes, https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true
Project-URL: source, https://github.com/microsoft/agent-framework/tree/main/python
Provides-Extra: all
Import-Name: agent_framework

# Get Started with Microsoft Agent Framework

Highlights

- Flexible Agent Framework: build, orchestrate, and deploy AI agents and multi-agent systems
- Multi-Agent Orchestration: Group chat, sequential, concurrent, and handoff patterns
- Plugin Ecosystem: Extend with native functions, OpenAPI, Model Context Protocol (MCP), and more
- LLM Support: OpenAI, Foundry, Anthropic, and more
- Runtime Support: In-process and distributed agent execution
- Multimodal: Text, vision, and function calling
- Cross-Platform: .NET and Python implementations

## Quick Install

```bash
pip install agent-framework-core
# Optional: Add Microsoft Foundry integration
pip install agent-framework-foundry
# Optional: Add OpenAI integration
pip install agent-framework-openai
```

Supported Platforms:

- Python: 3.11–3.15
- OS: Windows, macOS, Linux

Python 3.11 or later is required. Supported environments are subject to
[integration-specific limits](../../README.md#python-315-limitations).

## 1. Setup API Keys

Depending on the client you want to use, there are various environment variables you can set to configure the chat clients. This can be done in the environment itself, or with a `.env` file in your project root, some examples of environment variables include:

```bash
FOUNDRY_PROJECT_ENDPOINT=...
FOUNDRY_MODEL=...
...
OPENAI_API_KEY=sk-...
OPENAI_CHAT_COMPLETION_MODEL=...
OPENAI_CHAT_MODEL=...
...
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_ENDPOINT=...
AZURE_OPENAI_MODEL=...
```

You can also override environment variables by explicitly passing configuration parameters to the chat client constructor:

```python
from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient(
    api_key="",
    model="",
)
```

### Telemetry controls

Agent Framework adds its package/version User-Agent to supported client
requests. Approved Microsoft Foundry and Azure OpenAI request paths can also
carry a documented feature-usage token.

- `AGENT_FRAMEWORK_FEATURE_MASK_DISABLED=true` disables only the feature-usage
  token while retaining the package/version User-Agent.
- `AGENT_FRAMEWORK_USER_AGENT_DISABLED=true` disables the entire Agent Framework
  User-Agent contribution, including the feature token.

OpenTelemetry providers configured through `configure_otel_providers()` share a
resource containing `"microsoft.agent-framework": "True"` (a string) by default. This
resource attribute applies to logs, traces, and metrics, including other
instrumentation using those providers. Existing environment and explicit resource
attribute overrides retain their precedence. If you configure providers yourself,
use `agent_framework.observability.create_resource()` for each provider or add the
attribute to your own shared resource.

See the following [getting started samples](https://github.com/microsoft/agent-framework/tree/main/python/samples/01-get-started) for more information.

## 2. Create a Simple Agent

Create agents and invoke them directly:

```python
import asyncio
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

agent = Agent(
    client=OpenAIChatClient(),
    instructions="""
    1) A robot may not injure a human being...
    2) A robot must obey orders given it by human beings...
    3) A robot must protect its own existence...

    Give me the TLDR in exactly 5 words.
    """
)

result = asyncio.run(agent.run("Summarize the Three Laws of Robotics"))
print(result)
# Output: Protect humans, obey, self-preserve, prioritized.
```

## 3. Directly Use Chat Clients (No Agent Required)

You can use the chat client classes directly for advanced workflows:

```python
import asyncio
from agent_framework.openai import OpenAIChatClient
from agent_framework import Message, Role

async def main():
    client = OpenAIChatClient()

    response = await client.get_response([
        Message("system", ["You are a helpful assistant."]),
        Message("user", ["Write a haiku about Agent Framework."])
    ])
    print(response.messages[0].text)

    """
    Output:

    Agents work in sync,
    Framework threads through each task—
    Code sparks collaboration.
    """

asyncio.run(main())
```

## 4. Build an Agent with Tools and Functions

Enhance your agent with custom tools and function calling:

```python
import asyncio
from typing import Annotated
from random import randint
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient


def get_weather(
    location: Annotated[str, "The location to get the weather for."],
) -> str:
    """Get the weather for a given location."""
    conditions = ["sunny", "cloudy", "rainy", "stormy"]
    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."


def get_menu_specials() -> str:
    """Get today's menu specials."""
    return """
    Special Soup: Clam Chowder
    Special Salad: Cobb Salad
    Special Drink: Chai Tea
    """


async def main():
    agent = Agent(
        client=OpenAIChatClient(),
        instructions="You are a helpful assistant that can provide weather and restaurant information.",
        tools=[get_weather, get_menu_specials]
    )

    response = await agent.run("What's the weather in Amsterdam and what are today's specials?")
    print(response)

    # Output:
    # The weather in Amsterdam is sunny with a high of 22°C. Today's specials include
    # Clam Chowder soup, Cobb Salad, and Chai Tea as the special drink.

asyncio.run(main())
```

You can explore additional agent samples [here](https://github.com/microsoft/agent-framework/tree/main/python/samples/02-agents).

### MCP HTTP client ownership and cookies

**Breaking change:** HTTP clients created by `MCPStreamableHTTPTool` no longer persist
response cookies. This applies with or without a `header_provider`, including repeated
calls within the same MCP session. Connection reuse, timeout and redirect defaults,
and cleanup on close or reset are preserved. Explicit `Cookie` headers supplied through
`static_headers` or a `header_provider` are still supported.

Applications relying on cookie-based authentication, sessions, or load-balancer affinity
must supply an `httpx.AsyncClient` through `http_client=`. Supplied clients retain their
configuration and response-cookie handling and must be closed by the caller. Scope
cookie-bearing clients and MCP tool sessions to one authenticated principal; do not
share a user-specific cookie jar across users. Rejecting cookies does not partition
MCP protocol sessions or other server-side state between principals.

### MCP HTTP concurrency and timeouts

`MCPStreamableHTTPTool` and `FoundryToolbox` attach a separate header snapshot to each
outgoing HTTP request. Calls with identical effective static and dynamic headers can
overlap on one MCP session. A different identity waits for active operations before
reconnecting and refreshing discovery. Discovery, reset, close, and recovery are
exclusive against active network attempts on framework-owned MCP connections, with
or without a header provider. Same-identity Agent run preparation does not drain
active calls. Direct prompt calls resolve current headers rather than reusing an
inherited invocation snapshot; generated prompts resolve host runtime kwargs
separately from model arguments. Calls still share server-side session state;
applications must order state-dependent operations themselves.

Resource reads wait for replacement initialization before requiring the connection.
Catalog discovery restarts the complete snapshot once after a connection replacement,
without reusing old pages or cursors. A second replacement fails explicitly.

`request_timeout` bounds header admission and session reconciliation together, and
connection recovery separately from the RPC timeout. These are separate budgets,
not an end-to-end deadline. `None` disables these budgets. An admission timeout does
not cancel another caller's active operation. Cleanup may continue after a timeout
or cancellation so the lifecycle owner can finish releasing resources safely.
Caller-owned MCP clients retain their own RPC timeout policy and are not recreated.

Concurrent failures of the same connection share its replacement. Calling `close()`
interrupts older recovery so it cannot reopen the connection or retry the failed
operation after shutdown. A later explicit `connect()` remains supported.

## 5. Multi-Agent Orchestration

Coordinate multiple agents to collaborate on complex tasks using orchestration patterns:

```python
import asyncio
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient


async def main():
    # Create specialized agents
    writer = Agent(
        client=OpenAIChatClient(),
        name="Writer",
        instructions="You are a creative content writer. Generate and refine slogans based on feedback."
    )

    reviewer = Agent(
        client=OpenAIChatClient(),
        name="Reviewer",
        instructions="You are a critical reviewer. Provide detailed feedback on proposed slogans."
    )

    # Sequential workflow: Writer creates, Reviewer provides feedback
    task = "Create a slogan for a new electric SUV that is affordable and fun to drive."

    # Step 1: Writer creates initial slogan
    initial_result = await writer.run(task)
    print(f"Writer: {initial_result}")

    # Step 2: Reviewer provides feedback
    feedback_request = f"Please review this slogan: {initial_result}"
    feedback = await reviewer.run(feedback_request)
    print(f"Reviewer: {feedback}")

    # Step 3: Writer refines based on feedback
    refinement_request = f"Please refine this slogan based on the feedback: {initial_result}\nFeedback: {feedback}"
    final_result = await writer.run(refinement_request)
    print(f"Final Slogan: {final_result}")

    # Example Output:
    # Writer: "Charge Forward: Affordable Adventure Awaits!"
    # Reviewer: "Good energy, but 'Charge Forward' is overused in EV marketing..."
    # Final Slogan: "Power Up Your Adventure: Premium Feel, Smart Price!"

if __name__ == "__main__":
    asyncio.run(main())
```

**Note**: Sequential, Concurrent, Group Chat, Handoff, and Magentic orchestrations are available. See examples in [orchestration samples](https://github.com/microsoft/agent-framework/tree/main/python/samples/03-workflows/orchestrations).

## More Examples & Samples

- [Getting Started with Agents](https://github.com/microsoft/agent-framework/tree/main/python/samples/02-agents): Basic agent creation and tool usage
- [Chat Client Examples](https://github.com/microsoft/agent-framework/tree/main/python/samples/02-agents/chat_client): Direct chat client usage patterns
- [Foundry Integration](https://github.com/microsoft/agent-framework/tree/main/python/packages/foundry): Foundry integration
- [Workflows Samples](https://github.com/microsoft/agent-framework/tree/main/python/samples/03-workflows): Advanced multi-agent patterns

## Agent Framework Documentation

- [Agent Framework Repository](https://github.com/microsoft/agent-framework)
- [Python Package Documentation](https://github.com/microsoft/agent-framework/tree/main/python)
- [.NET Package Documentation](https://github.com/microsoft/agent-framework/tree/main/dotnet)
- [Design Documents](https://github.com/microsoft/agent-framework/tree/main/docs/design)
- [Learn Documentation](https://learn.microsoft.com/agent-framework/)

