Python 2026 중요 변경 가이드

이 문서에서는 코드에 영향을 줄 수 있는 주요 변경 내용 및 향상된 기능을 포함하여 2026년 초부터 Python 릴리스의 중요한 변경 내용을 모두 나열합니다. 각 변경 내용은 다음과 같이 표시됩니다.

🔴 호환성 중단 — 업그레이드하려면 코드를 변경해야 합니다.
🟡 향상된 기능 - 새로운 기능 또는 개선 사항; 기존 코드가 계속 작동합니다.

이 문서는 모든 2026 릴리스에서 중요한 Python 변경 내용을 추적하므로 버전 간에 업그레이드할 때 중요한 변경 내용을 놓치지 않도록 참조하세요. 특정 항목(예: 옵션 마이그레이션)에 대한 자세한 업그레이드 지침은 연결된 업그레이드 가이드 또는 연결된 PR을 참조하세요.

미공개

🔴 랩은 별도로 설치되고 Foundry는 프로젝트 2.6을 지원합니다.

PR:#8188

agent-framework 및 agent-framework-core[all]는 더 이상 실험용 agent-framework-lab 패키지를 설치하지 않습니다. 각 랩 모듈을 명시적으로 설치합니다.

pip install "agent-framework-lab[gaia]"
pip install "agent-framework-lab[tau2]"
pip install "agent-framework-lab[lightning]"

랩은 이제 릴리스된 에이전트 프레임워크 패키지와 독립적으로 실험적 종속성을 해결합니다. agent-framework-foundry 패키지는 agent-framework-openai를 지원하며 OpenAI 3 호환 azure-ai-projects>=2.2.0,<2.7.0 버전을 사용합니다. 이러한 분리를 통해 Foundry 애플리케이션은 랩의 OpenAI 2 호환 종속성 제약 조건을 재정의하지 않고도 Azure AI Projects 2.4~2.6을 사용할 수 있습니다.

🔴 GitHub Copilot 작업 영역 파일 후크는 선택 사항입니다

PR:#7517

GitHubCopilotAgent는 기본적으로 작업 디렉터리에서 .github/hooks/를 더 이상 불러오지 않습니다. 신뢰하는 작업 디렉터리에 대해서만 후크를 사용하도록 설정합니다.

from agent_framework.github import GitHubCopilotAgent, GitHubCopilotOptions

agent = GitHubCopilotAgent(
    default_options=GitHubCopilotOptions(enable_file_hooks=True),
)

파일 후크는 호스트에서 명령을 실행하며, on_permission_request 또는 기타 도구 승인 콜백의 통제를 받지 않습니다. 후크가 존재하고 생략 enable_file_hooks하면 에이전트가 기본값을 False 지정하고 경고를 한 번 기록합니다. 명시적으로 설정하면 enable_file_hooks=False 해당 경고 없이 후크가 비활성화됩니다. 구성 지침은 작업 영역 파일 후크 제어를 참조하세요.

🔴 파일 백업 스토리지는 공유 경로 정규화를 사용합니다.

PR:#8123

이제 파일 기반 세션, 메모리 저장소 및 할 일 저장소는 모두 하나의 공통 스토리지 키 매핑을 통해 폴더 이름을 결정합니다. 대문자, 경로 구분자, 유니코드 문자 또는 기타 안전하지 않은 문자가 포함된 ID 및 범위는 업그레이드 후 다른 위치로 해석될 수 있습니다.

기존 데이터는 자동으로 이동되지 않습니다. 보존해야 하는 경우 이전 파일 또는 디렉터리를 새로 파생된 위치로 마이그레이션합니다. 중첩된 경로가 아닌 하나의 불투명 네임스페이스 키로 처리 FileMemoryProvider.scope 합니다. 예를 들어 인 tenants/alice 코딩된 폴더 하나에 매핑됩니다.

TodoFileStore 는 소유자 ID에 대한 공유 매핑을 사용하지만 포함 / 하거나 \포함하는 세션 ID를 거부합니다. todo 데이터를 마이그레이션하기 전에 해당 세션 ID를 정식화합니다.

🔴 `SecretString`는 더 이상 `str`를 상속하지 않음

PR:#8127

SecretString 이제 문자열 변환, 서식 및 연결을 마스킹합니다. JSON 직렬화를 포함해 실제 str가 필요한 API는 더 이상 래퍼를 암묵적으로 허용하지 않습니다. 자격 증명이 필요한 경계에서 명시적으로 값을 추출합니다.

Before:

payload = json.dumps({"api_key": secret})

After:

payload = json.dumps({"api_key": secret.get_secret_value()})

추출된 값은 일반 문자열이며 실수로 인한 로깅 또는 서식 지정으로부터 더 이상 보호되지 않습니다.

🔴 미들웨어 입력에는 시퀀스가 필요하며 에이전트 후크는 별도로 설치됩니다.

PR:#7918

에이전트 생성자, 실행별 미들웨어 입력 및 create_harness_agent() 더 이상 단일 미들웨어 값을 허용하지 않습니다. 미들웨어를 시퀀스로 전달합니다. Agent Hooks 번들은 해당 시퀀스를 구성하는 요소 중 하나로 계속 지원됩니다.

agent-framework-core[agent-hooks] 추가 항목이 제거됩니다. agent-hooks-sdk를 직접 설치합니다.

Before:

agent = Agent(client=client, middleware=hooks)

After:

pip install agent-hooks-sdk

agent = Agent(client=client, middleware=[hooks])

python-1.16.0(2026년 8월 27일)

릴리스 정보:python-1.16.0

🟡 프로그래밍 방식의 OpenTelemetry 공급자 구성

PR:#7703

configure_otel_providers() 이제 서비스 메타데이터, 리소스 특성 및 OTLP 내보내기 옵션을 직접 수락합니다. 명시적 서비스 메타데이터가 환경 값보다 우선합니다. 리소스 속성은 환경 속성보다 우선하여 병합됩니다. 신호별 OTLP 엔드포인트 및 헤더 변수는 기본 프로그래밍 방식 설정보다 더 구체적으로 유지됩니다.

python-1.15.0(2026년 8월 21일)

릴리스 정보:python-1.15.0

🔴 OpenTelemetry GenAI 의미 체계 규칙 통합

PR:#7673

이제 Agent Framework는 gen_ai.system 대신 gen_ai.provider.name를 포함한 최신 실험적 GenAI span 특성을 기본적으로 사용합니다. gen_ai_latest_experimental을(를) 대/소문자를 구분하는 OTEL_SEMCONV_STABILITY_OPT_IN 토큰이 생략된 값으로 설정하여 v1.36 span 속성을 선택합니다. v1.36 메시지 및 선택 이벤트는 독립적으로 선택되며 중요한 데이터가 캡처될 때 기본적으로 사용하도록 설정된 상태로 유지되며 계속 사용합니다 gen_ai.system. ENABLE_MESSAGE_EVENTS=false을(를) 표시되지 않도록 설정합니다.

🟡 함수 미들웨어는 다음을 사용하여 중단할 수 있습니다. `MiddlewareFailure`

PR:#7562

함수 미들웨어는 실행을 중단해야 할 때 복구 가능한 도구 오류로 처리되는 대신 MiddlewareFailure를 발생시킬 수 있습니다. 함수 호출 루프는 이 예외를 호출자에게 전파하고 실행 중인 형제 도구 호출을 취소합니다. 이 예외를 미들웨어에서 처리하지 마세요. 처리할 경우 실행이 계속 진행될 수 있습니다.

에이전트 및 채팅 미들웨어는 이미 일반적인 예외를 전파합니다. 함수 미들웨어에 치명적인 오류 시 닫힘 동작이 명확히 필요한 경우 MiddlewareFailure를 사용하세요.

python-1.14.0(2026년 8월 14일)

릴리스 정보:python-1.14.0

🟡 암호화된 추론이 Foundry 채팅에 옵트인됨

PR:#7536

FoundryChatClient 더 이상 기본적으로 요청하지 reasoning.encrypted_content 않습니다. 기본값은 지원되지 않는 모델의 오류를 방지합니다. 해당 기능을 지원하는 배포의 경우 default_options={"include": ["reasoning.encrypted_content"]}로 옵트인하세요.

🔴 [베타] Foundry 호스트 에이전트 상태가 Foundry 상태 저장소로 이동

PR:#7533

PR #7533은 베타 FoundrySessionStore(path) 패키지에서 agent-framework-foundry-hosting을 제거합니다. 이제 호스트는 에이전트 세션, 워크플로 검사점 및 함수 승인에 대해 Foundry 상태 저장소 지원 기본값을 사용합니다 FoundryAgentSessionStore .

import문과 FoundrySessionStore의 생성을 제거합니다.
ResponsesHostServer가 기본 공급자를 만들도록 합니다. 사용자 지정 스토리지의 경우 agent_session_store_provider, checkpoint_store_provider, 또는 function_approval_store_provider를 전달하세요.
기존 파일 기반 상태는 자동으로 마이그레이션되지 않습니다.

현재 공급자 모델에 대해서는 상태 유지 및 장기 실행 대화 처리를 참조하세요.

🔴 함수 워크플로 정의를 실행하기 전에 빌드

PR:#7521

PR #7521이 stateless FunctionalWorkflowDefinition를 반환하도록 @workflow 변경되었습니다. 상태 저장 .build()을 만들려면 FunctionalWorkflow을 호출합니다. .as_agent() 또는 .run()을 호출하기 전에 워크플로를 빌드하고, 체크포인트 스토리지를 .build()에 전달하세요.

Before:

@workflow(checkpoint_storage=storage)
async def pipeline(data: str) -> str:
    return await process(data)

result = await pipeline.run("input")
agent = pipeline.as_agent()

After:

@workflow
async def pipeline(data: str) -> str:
    return await process(data)

workflow_instance = pipeline.build(checkpoint_storage=storage)
result = await workflow_instance.run("input")
agent = workflow_instance.as_agent()

실행 및 재생 상태가 격리된 상태로 유지되도록 각 논리 호출자 또는 세션에 대해 별도의 워크플로 인스턴스를 빌드합니다.

🟡 에이전트 후크가 장애 조치(fail-closed) 인터셉션 계약을 추가합니다.

PR:#7515

Agent Framework는 create_agent_hooks_middleware() 및 create_agent_hooks_middleware_from_emitter()를 통해 AGENT-HOOKS-0.1 계약에 대한 실험적 지원을 추가합니다. 미들웨어 번들은 에이전트, 모델, 함수 인터셉션 지점을 포괄하며, fail-closed 평결 강제 적용, 변환 결과 쓰기-반영, 버퍼링된 스트리밍, 평결 기반 영속화를 지원합니다.

현재 패키지 및 미들웨어 계약의 경우 agent-hooks-sdk를 직접 설치하고, 반환된 번들을 middleware=[hooks]와 같은 순서로 전달합니다. 자세한 내용은 에이전트 후크를 참조하세요.

python-1.8.0(2026년 6월 4일)

릴리스 정보:python-1.8.0

🔴 `github-copilot-sdk`가 호환성을 깨뜨리는 API 변경 사항과 함께 v1.0.0으로 업그레이드되었습니다

PR:#6292

PR #6292은 GA 버전에 도입된 모든 호환성을 깨뜨리는 API 변경 사항에 맞춰 agent-framework-github-copilot를 github-copilot-sdk 1.0.0b2에서 정식 정적 릴리스인 1.0.0으로 업그레이드합니다.

SubprocessConfig 제거됨 — RuntimeConnection.for_stdio(path=...)에서 CopilotClient + 키워드 인수를 사용하세요(connection, log_level, base_directory).
가져오기 경로가 이동됨 — copilot.generated.session_events → copilot.session_events.
설정 이름이 바뀌었습니다copilot_home . → base_directory; 환경 변수가 이제 GITHUB_COPILOT_BASE_DIRECTORY (였습니다 GITHUB_COPILOT_COPILOT_HOME)입니다.
사용 권한 처리기 - 대신 구체적인 의사 결정 유형을 PermissionRequestResult(kind=...)사용합니다. 기본 제공 PermissionHandler.approve_all 은 수동 승인 패턴을 대체합니다.
기본 거부 처리기 - 이제 반환 PermissionDecisionUserNotAvailable() 됩니다(일치하는 SDK 대체 동작).
권한 처리기 유형 - 이제 동기화 및 비동기 콜백(Callable[..., PermissionRequestResult | Awaitable[PermissionRequestResult]])을 모두 지원합니다.

Before:

from copilot import CopilotClient, SubprocessConfig
from copilot.generated.session_events import PermissionRequest
from copilot.session import PermissionRequestResult

# Client construction
client = CopilotClient(SubprocessConfig(cli_path="/path/to/cli", log_level="debug", copilot_home="/custom/home"))

# Permission handler
def approve_shell(request: PermissionRequest, context: dict[str, str]) -> PermissionRequestResult:
    if request.kind == "shell":
        return PermissionRequestResult(kind="approved")
    return PermissionRequestResult(kind="denied-interactively-by-user")

# Agent
agent = GitHubCopilotAgent(default_options={"copilot_home": "/custom/home", "on_permission_request": approve_shell})

After:

from copilot import CopilotClient, RuntimeConnection
from copilot.generated.rpc import PermissionDecisionDeniedInteractivelyByUser, PermissionDecisionUserNotAvailable
from copilot.session import PermissionHandler, PermissionRequestResult
from copilot.session_events import PermissionRequest

# Client construction
client = CopilotClient(connection=RuntimeConnection.for_stdio(path="/path/to/cli"), log_level="debug", base_directory="/custom/home")

# Permission handler — use concrete decision types or PermissionHandler.approve_all
def approve_shell(request: PermissionRequest, context: dict[str, str]) -> PermissionRequestResult:
    if request.kind == "shell":
        return PermissionHandler.approve_all(request, context)
    return PermissionDecisionUserNotAvailable()

# Agent
agent = GitHubCopilotAgent(default_options={"base_directory": "/custom/home", "on_permission_request": approve_shell})

🟡 `FunctionInvocationContext`을 통한 도구의 점진적 노출

PR:#6233

FunctionInvocationContext를 사용하여 실행 중에 도구를 점진적으로 표시하는 지원을 추가합니다. 이제 동일한 에이전트 실행 내의 이전 도구 결과에 따라 도구를 동적으로 추가하거나 제거할 수 있습니다.

패턴, 주의 사항 및 도구 순서 지정 예제를 포함한 전체 설명서는 도구 가용성 제어를 참조하세요.

🟡 MCP 기반 기술 검색(`McpSkillsSource`)

PR:#6169

McpSkillsSource에 agent-framework-core를 추가하여 MCP 서버를 통해 스킬을 검색하고 로드할 수 있도록 합니다.

🟡 Converse API를 통한 Bedrock 기본 구조화된 출력 지원

PR:#6052

agent-framework-bedrock 이제 AWS Bedrock Converse API를 통해 네이티브 구조적 출력 지원을 구현하여 response_format Bedrock 모델에서 작업할 수 있습니다.

🟡 Foundry Adaptive Evals 통합(루브릭 생성)

PR:#6101

평가 워크플로에서 자동화된 루브릭 생성을 위해 agent-framework-foundry Foundry Adaptive Evals 통합을 추가합니다.

🟡 Mistral AI 임베딩 클라이언트 패키지

PR:#5480

Mistral AI 포함 클라이언트를 제공하는 새 agent-framework-mistral 패키지입니다.

🟡 `agent-framework-declarative`가 릴리스 후보로 승격됨

PR:#6256

패키지는 agent-framework-declarative 베타에서 릴리스 후보 단계로 승격됩니다.

python-1.7.0(2026년 5월 28일)

릴리스 정보:python-1.7.0

🔴 선언적: Python 전용 작업이 제거되고 별칭 종류 이름이 C# 정식 이름으로 바뀌었습니다.

PR:#6126

PR #6126 Python 전용 선언적 작업을 제거하고 언어 간 일관성을 위해 C# 정식 이름과 일치하도록 별칭 종류의 이름을 바꿉니다.

C# 해당 항목이 없는 Python 전용 선언적 작업 형식이 제거됩니다.
이제 작업 별칭 종류가 C# 명명 규칙에 맞춰집니다. 그에 따라 기존 선언적 YAML/JSON 파일을 업데이트합니다.

🟡 `HarnessAgent` 및 백그라운드 에이전트는 공급자를 활용합니다

PR:#6041, #6069

HarnessAgent에 agent-framework-core를 추가하여 배경 처리를 위한 하네스 지원 에이전트 패턴을 사용할 수 있도록 합니다.

🟡 참조된 작업 ID 및 입력 필요 지원이 포함된 `A2AAgentSession`

PR:#5980

A2AAgentSession를 agent-framework-a2a 및 agent-framework-core에 추가하고, A2A 프로토콜 상호 작용을 위한 참조된 작업 ID 및 입력 필수 흐름을 지원합니다.

🟡 실험적 프롬프트 에이전트 변환 및 배포 API

PR:#5959

프롬프트 정의를 에이전트로 변환하고 프로그래밍 방식으로 배포하기 위한 실험적 API agent-framework-foundry 를 추가합니다.

python-1.6.0(2026년 5월 21일)

릴리스 정보:python-1.6.0

🔴 기본적으로 활성화된 계측 기능

PR:#5865

PR #5865은 agent-framework-core 및 agent-framework-foundry에서 기본적으로 OpenTelemetry 계측을 활성화합니다.

이제 에이전트 실행 시 명시적 옵트인 없이도 텔레메트리 스팬이 자동으로 생성됩니다.
이전에 계측을 사용하지 않도록 설정했거나 사용자 지정 원격 분석 파이프라인이 있는 경우 기본 동작이 충돌하지 않는지 확인합니다.
비활성화하려면 해당되는 경우 enable_instrumentation=False를 전달합니다.

Before:

from agent_framework import Agent
from agent_framework.observability import configure_otel_providers

# Had to explicitly enable instrumentation
configure_otel_providers(enable_console_exporters=True)

agent = Agent(client=client, enable_instrumentation=True)

After:

from agent_framework import Agent

# Instrumentation is now on by default — no opt-in needed
agent = Agent(client=client)

# To explicitly disable:
agent = Agent(client=client, enable_instrumentation=False)

🟡 로컬 및 Docker 실행 지원이 있는 셸 도구

PR:#5664

로컬 실행과 Docker 기반 샌드박스 실행을 모두 지원하는 기본 제공 셸 도구를 agent-framework-core 추가합니다.

🟡 새 `agent-framework-monty` CodeAct 공급자 패키지

PR:#5915

Monty 기반 CodeAct 통합(알파 단계)을 위한 agent-framework-monty 패키지를 소개합니다.

python-1.4.0(2026년 5월 14일)

릴리스 정보:python-1.4.0

🔴 [실험적 기술 API] 파일 기술 폴더 검색을 agentskills.io 사양에 맞게 조정

PR:#5807

PR #5807 은 실험적 기술 API를 업데이트하여 파일 기반 기술 폴더 검색을 agentskills.io 사양에 맞춥니다.

기술 폴더 확인 논리가 변경되었습니다. 실험적 기술 API를 사용하는 경우 사용자 지정 기술 디렉터리 레이아웃을 업데이트합니다.

🔴 [실험적 기술 API] 기술 사양 메타데이터 추출 `SkillFrontmatter`

PR:#5775

PR #5775 은 기술 사양 메타데이터를 전용 SkillFrontmatter 데이터 클래스로 이동합니다.

기술 메타데이터 필드에 직접 액세스하는 경우 특성을 사용하도록 SkillFrontmatter 참조를 업데이트합니다.

🔴 DevUI: 기본 접근 제어 및 CORS 보안 태세 강화

PR:#5740

PR #5740은 agent-framework-devui에 대한 기본 액세스 제어 및 CORS 구성을 강화합니다.

이제 기본 CORS 원본이 더 제한적입니다.
DevUI 설정이 사용자 지정 도메인의 원본 간 액세스를 사용하는 경우 허용된 원본을 명시적으로 구성합니다.

🔴 A2A: a2a-sdk v1.0으로 마이그레이션

PR:#5752

PR #5752은 agent-framework-a2a을 a2a-sdk v1.0으로 마이그레이션합니다.

A2A 프로토콜 형식 및 전송 API는 a2a-sdk 1.0 규칙을 따릅니다.
A2A 프로토콜 형식과 직접 상호 작용하는 코드를 업데이트합니다.

🟡 AG-UI: 도구 결과 표시 채널 및 릴리스 후보로 승격

PR:#5762, #5844

도구 결과 표시 채널을 agent-framework-ag-ui 추가하고 패키지를 릴리스 후보 단계로 승격합니다.

python-1.3.0(2026년 5월 7일)

릴리스 정보:python-1.3.0

🔴 [실험적 기술 API] 다중 소스 아키텍처에 대한 에이전트 기술 재구성

PR:#5584

PR #5584 은 다중 소스 기술 로드를 지원하기 위해 실험적 기술 API를 재구성합니다.

실험적 기술 기능에 대한 기술 등록 및 검색 논리가 변경되었습니다.
실험적 기술 API를 사용하는 경우 새 다중 원본 로드 규칙을 검토합니다.

🟡 `ClassSkill` 클래스 기반 스킬 정의용

PR:#5678

선언적 메타데이터와 자동 메서드 검색을 사용하는 클래스 기반 스킬 정의에 ClassSkill를 agent-framework-core에 추가합니다.

🟡 정보 흐름 제어 프롬프트 삽입 방어

PR:#5331

프롬프트 삽입 공격을 방어하는 agent-framework-core 데 도움이 되는 정보 흐름 제어 메커니즘을 추가합니다.

🟡 `github-copilot-sdk` v1.0.0b2로 업그레이드됨

PR:#5665

agent-framework-github-copilot에서 github-copilot-sdk>=1.0.0b2(으)로 업그레이드하고, instruction_directories, copilot_home 구성 및 세션 재개 시 런타임 옵션 전달을 추가합니다.

🟡 Claude 및 GitHub Copilot 에이전트에서 `approval_mode` 적용

PR:#5562

agent-framework-claude 및 agent-framework-github-copilot는 이제 다른 에이전트 구현과 일관되게 함수 도구에 approval_mode 데코레이터를 적용하도록 강제합니다.

🟡 OpenAI 및 Gemini `allowed_tools` 도구 선택 지원

PR:#5322

도구 선택에 allowed_tools대한 agent-framework-openai 지원을 추가하여 모델이 호출할 수 있는 도구를 제한할 수 있습니다.

python-1.2.2(2026년 4월 29일)

릴리스 정보:python-1.2.2

🔴 오케스트레이션 터미널 출력은 다음과 같이 표준화됩니다. `AgentResponse`

PR:#5301

PR #5301 은 오케스트레이션 터미널 출력을 AgentResponse 표준화하므로 Workflow.as_agent() 최종 답변만 반환합니다.

순차 승인(with_request_info) 및 동시(intermediate_outputs=True) 흐름은 이제 동일한 출력 계약을 따릅니다.
오케스트레이션 결과를 직접 사용하는 경우 원시 텍스트나 혼합 유형 대신 AgentResponse개체가 반환될 것으로 예상해야 합니다.

Before:

# Orchestration returned mixed types (raw strings, dicts, etc.)
result = await workflow.as_agent().run("Draft a report")
text = str(result)  # had to handle various types

After:

# Orchestration now always returns AgentResponse
result = await workflow.as_agent().run("Draft a report")
text = result.text  # consistent AgentResponse API

🟡 Azure AI Content Understanding 컨텍스트 공급자

PR:#4829

새 알파 패키지 agent-framework-azure-contentunderstanding - 파일 첨부 파일(문서, 이미지, 오디오, 비디오)을 자동으로 분석하고 구조화된 결과를 LLM 컨텍스트에 삽입합니다.

🟡 파운드리 호스팅을 통한 호스트된 지속성 워크플로 지원

PR:#5531

호스트된 지속성 워크플로 지원을 agent-framework-foundry-hosting추가하여 전체 대화 기록을 워크플로 에이전트에 전파합니다.

python-1.1.0(2026년 4월 21일)

릴리스 정보:python-1.1.0

🔴 `CosmosCheckpointStorage` 기본적으로 피클 역직렬화가 제한됨

PR:#5200

CosmosCheckpointStorage는 이제 기본적으로 제한된 pickle 역직렬화를 사용하며, FileCheckpointStorage의 동작과 일치합니다.

체크포인트에 애플리케이션에서 정의한 형식이 포함되어 있다면 allowed_checkpoint_types=["my_app.models:MyState"]를 통해 전달하세요.
이것이 없으면 사용자 지정 형식을 역직렬화할 때 WorkflowCheckpointException 예외가 발생합니다.

Before:

from agent_framework.azure.cosmos import CosmosCheckpointStorage

storage = CosmosCheckpointStorage(endpoint=endpoint, database="mydb", container="checkpoints")

After:

from agent_framework.azure.cosmos import CosmosCheckpointStorage

storage = CosmosCheckpointStorage(
    endpoint=endpoint,
    database="mydb",
    container="checkpoints",
    allowed_checkpoint_types=["my_app.models:MyState"],
)

🟡 `GeminiChatClient` 추가

PR:#4847

Google Gemini API 및 Vertex AI 지원용 새 agent-framework-gemini 패키지(GeminiChatClient 포함)

🟡 Hyperlight CodeAct 패키지

PR:#5185

Hyperlight 기반 CodeAct 샌드박스 코드 실행을 위한 새 agent-framework-hyperlight 패키지입니다.

🟡 Foundry 도구 상자 지원

PR:#5346

agent-framework-foundry에 Foundry 도구 상자 지원을 추가하여 Azure AI Foundry의 관리형 도구 구성을 사용할 수 있도록 합니다.

🟡 `AgentResponse` 및 `AgentResponseUpdate`의 `finish_reason`

PR:#5211

finish_reason 및 AgentResponse에 AgentResponseUpdate 필드를 추가하여 사용자가 모델이 생성을 중단한 이유를 확인할 수 있도록 합니다.

🟡 Foundry에서 호스트된 에이전트 V2 지원

PR:#5379

최신 Foundry 에이전트 서비스 기능을 지원하기 위해 agent-framework-foundry에 호스팅된 에이전트 V2 지원을 추가합니다.

python-1.0.1(2026년 4월 9일)

릴리스 정보:python-1.0.1

🔴 `FileCheckpointStorage`의 제한된 피클 역직렬화(보안 강화)

PR:#4941

이제 검사점 역직렬화는 기본적으로 제한된 unpickler를 통해 흐르며, 이는 기본 제공 안전 Python 형식 집합과 모든 agent_framework 프레임워크 형식만 허용합니다.

애플리케이션이 검사점에 사용자 지정 형식을 저장하는 경우, 해당 식별자를 새 "module:qualname" 생성자 매개변수를 통해 전달하세요. 그렇지 않으면 로드 시 allowed_checkpoint_types 예외가 발생합니다.
자세한 내용은 보안 고려 사항을 참조하세요.

Before:

from agent_framework.workflows import FileCheckpointStorage

storage = FileCheckpointStorage(directory="./checkpoints")

After:

from agent_framework import FileCheckpointStorage

storage = FileCheckpointStorage(
    directory="./checkpoints",
    allowed_checkpoint_types=["my_app.models:MyState", "my_app.models:TaskResult"],
)

🔴 핸드오프 워크플로 컨텍스트 관리 수정

PR:#5136

PR #5136 은 핸드오프 워크플로 컨텍스트 관리를 수정합니다. 이는 동작 변경입니다. 이제 핸드오프 에이전트는 전환 간에 격리된 컨텍스트를 올바르게 유지 관리합니다.

🟡 워크플로용 Cosmos DB NoSQL 체크포인트 저장소

PR:#4916

Python 워크플로에 대한 Cosmos DB NoSQL 지원 검사점 스토리지를 제공하는 새로운 agent-framework-azure-cosmos 패키지입니다.

python-1.0.0(2026년 4월 2일)

릴리스 정보:python-1.0.0

이 섹션에서는 python-1.0.0rc6 이후 이루어진 중요한 Python 변경 내용을 포착하고, 이제 python-1.0.0에 포함된 것을 다룹니다.

🔴 `Message(..., text=...)` 구조가 이제 완전히 제거되었습니다.

PR:#5062

PR #5062은 여전히 text=...로 Message객체를 생성하던 프레임워크 측의 마지막 코드 경로를 제거하여 이전의 Python 메시지 모델 정리 작업을 완료합니다.

Message(role="user", contents=["Hello"])로 문자 메시지를 작성하고 Message(role="user", text="Hello") 대신 사용합니다.
워크플로 요청, 사용자 지정 미들웨어 응답, 오케스트레이션 도우미 및 마이그레이션 코드를 포함하여 메시지를 직접 생성하는 모든 위치에 적용됩니다.
내부의 contents=[...] 일반 문자열은 여전히 자동으로 텍스트 콘텐츠로 정규화되므로 contents=["Hello"] 가장 간단한 텍스트 전용 형식으로 유지됩니다.

Before:

message = Message(role="assistant", text="Hello")

After:

message = Message(role="assistant", contents=["Hello"])

🟡 릴리스된 Python 패키지는 더 이상 필요하지 않습니다. `--pre`

PR:#5062

PR #5062은 주요 Python 패키지를 1.0.0으로 승격하고, 릴리스된 패키지와 프리릴리스 패키지를 명확하게 구분하기 위해 설치 지침을 업데이트합니다.

이제 agent-framework, agent-framework-core, agent-framework-openai 그리고 agent-framework-foundry는 릴리스된 패키지이므로 더 이상 --pre가 필요하지 않습니다.
Beta 커넥터(agent-framework-ag-ui, agent-framework-azurefunctions, agent-framework-copilotstudio, agent-framework-foundry-local, agent-framework-github-copilot, agent-framework-mem0, agent-framework-ollama)에는 여전히 --pre이(가) 필요합니다.
단일 설치 명령에 베타 패키지가 포함된 경우 해당 명령을 유지합니다 --pre .

🔴 이제 Foundry는 Python 포함 및 모델 엔드포인트 설정을 소유합니다.

PR:#5056

PR #5056 은 독립 실행형 agent-framework-azure-ai 패키지를 제거하고 Python 포함 표면을 agent-framework-foundry 및 agent_framework.foundry로 이동합니다.

FoundryEmbeddingClient에서 FoundryEmbeddingOptions, FoundryEmbeddingSettings, 및 agent_framework.foundry을 사용합니다.
Foundry 채팅, 서비스 관리 에이전트, 메모리 제공자 및 임베딩을 위해 agent-framework-foundry을 설치합니다.
agent_framework.azure를 더 이상 내보내지 않습니다.AzureAIInferenceEmbeddingClientAzureAIInferenceEmbeddingOptionsAzureAIInferenceEmbeddingSettingsAzureAISettings
이제 Foundry embeddings는 FOUNDRY_MODELS_ENDPOINT, FOUNDRY_MODELS_API_KEY, FOUNDRY_EMBEDDING_MODEL 및 선택적으로 FOUNDRY_IMAGE_EMBEDDING_MODEL를 사용합니다.
FoundryChatClient 및 FoundryAgent는 여전히 FOUNDRY_PROJECT_ENDPOINT 및 FOUNDRY_MODEL와 같은 프로젝트 엔드포인트 설정을 사용합니다.

Before:

import os

from agent_framework.azure import AzureAIInferenceEmbeddingClient

client = AzureAIInferenceEmbeddingClient(
    endpoint=os.environ["AZURE_AI_SERVICES_ENDPOINT"],
    model=os.environ["AZURE_AI_EMBEDDING_NAME"],
    credential=credential,
)

After:

import os

from agent_framework.foundry import FoundryEmbeddingClient

client = FoundryEmbeddingClient(
    endpoint=os.environ["FOUNDRY_MODELS_ENDPOINT"],
    api_key=os.environ["FOUNDRY_MODELS_API_KEY"],
    model=os.environ["FOUNDRY_EMBEDDING_MODEL"],
)

🔴 워크플로는 이제 명시적 버킷을 통해 런타임 kwargs를 라우팅합니다.

PR:#5010

PR #5010는 Python workflow.run(...)을 업데이트하여 런타임 kwargs를 제네릭 전달 function_invocation_kwargs= 대신 명시적으로 client_kwargs= 및 **kwargs로 전달합니다.

플랫 매핑은 전역으로 처리되며 워크플로의 일치하는 모든 에이전트 실행기로 전달됩니다.
하나 이상의 최상위 키가 실행기 ID와 일치하는 경우 전체 매핑은 실행기별 대상 지정으로 처리되고 각 실행기는 자체 항목만 받습니다.
사용자 지정 AgentExecutor(id="...") 및 기타 명시적 워크플로 실행기 ID는 대상으로 하는 키입니다.
동일한 전역 및 대상 규칙이 둘 다 function_invocation_kwargs 에 client_kwargs적용됩니다.

Before:

await workflow.run(
    "Draft the report",
    db_config={"connection_string": "..."},
    user_preferences={"format": "markdown"},
)

After:

await workflow.run(
    "Draft the report",
    function_invocation_kwargs={
        "researcher": {
            "db_config": {"connection_string": "..."},
        },
        "writer": {
            "user_preferences": {"format": "markdown"},
        },
    },
)

🟡 `GitHubCopilotAgent` 이제 각 호출을 중심으로 컨텍스트 공급자를 실행합니다.

PR:#5013

PR #5013은 GitHubCopilotAgent가 context_providers를 전달받기는 하지만 실제로 호출하지는 않던 Python의 동작 격차를 수정합니다.

before_run() 는 Copilot 프롬프트가 전송되기 전에 실행됩니다.
공급자가 추가한 메시지 및 지침은 Copilot CLI에 도달하는 프롬프트에 포함됩니다.
after_run() 는 스트리밍 경로를 포함하여 최종 응답이 어셈블된 후 실행됩니다.

이미 전달한 context_providersGitHubCopilotAgent경우 마이그레이션이 필요하지 않습니다. 이제 후크는 Python 에이전트 화면의 나머지 부분과 일관되게 작동합니다.

🟡 이제 구조적 출력은 Pydantic 모델 외에도 JSON 스키마 매핑을 허용합니다.

PR:#5022

PR #5022 은 Python 구조적 출력 구문 분석을 확장하므로 response_format Pydantic 모델 또는 JSON 스키마 매핑이 될 수 있습니다.

Pydantic 모델은 여전히 response.value에서 형식이 지정된 모델 인스턴스로 구문 분석됩니다.
이제 JSON 스키마 매핑은 response.value에서 JSON 호환 Python 값(일반적으로 dict 또는 list)으로 구문 분석됩니다.
스트림에서 최종 응답을 수집할 때 동일한 구문 분석 규칙이 적용됩니다.

이는 호환성이 손상되는 변경이 아닌 향상된 기능이지만 스키마를 JSON과 유사한 사전으로 이미 저장하고 있는지 아는 것이 유용합니다.

python-1.0.0rc6

이 섹션에서는 함께 제공되거나 추적된 중요한 Python 변경 내용을 캡처합니다 python-1.0.0rc6.

🔴 모델 선택은 다음에서 표준화됩니다. `model`

PR:#4999

PR #4999 은 생성자, 형식화된 옵션, 에이전트 기본값, 응답 개체 및 환경 변수에서 Python 쪽 모델 선택 정리를 완료합니다.

이전에 model을(를) 사용한 모든 위치에서 model_id을(를) 사용합니다.
Agent.default_options 및 options={...} 실행 시 이제 "model"이(가) 아닌 "model_id"을(를) 예상합니다.
응답 개체는 response.model이며, response.model_id이 아닙니다.
이제 OpenAI 설정에서 OPENAI_MODEL, OPENAI_CHAT_MODEL, OPENAI_CHAT_COMPLETION_MODEL, OPENAI_EMBEDDING_MODEL를 사용합니다.
이제 Azure OpenAI 설정은 AZURE_OPENAI_MODEL, AZURE_OPENAI_CHAT_MODEL, AZURE_OPENAI_CHAT_COMPLETION_MODEL 및 AZURE_OPENAI_EMBEDDING_MODEL를 사용합니다.
이제 Anthropic은 ANTHROPIC_CHAT_MODEL을 사용하며, Foundry Local은 FOUNDRY_LOCAL_MODEL을 사용합니다.
또한 Anthropic 패키지는 공급자 호스팅 래퍼(예: AnthropicFoundryClient, AnthropicBedrockClient및 AnthropicVertexClient)를 추가합니다.

Before:

from agent_framework.anthropic import AnthropicClient

client = AnthropicClient(model_id="claude-sonnet-4-5-20250929")
response = await client.get_response(
    "Hello!",
    options={"model_id": "claude-sonnet-4-5-20250929"},
)

After:

from agent_framework.anthropic import AnthropicClient

client = AnthropicClient(model="claude-sonnet-4-5-20250929")
response = await client.get_response(
    "Hello!",
    options={"model": "claude-sonnet-4-5-20250929"},
)

🔴 컨텍스트 공급자는 모델 호출당 미들웨어를 추가하고 기록을 유지할 수 있습니다.

PR:#4992

PR #4992 은 Python 컨텍스트 공급자 파이프라인을 업데이트하고 다중 호출 실행 중에 프레임워크 관리 기록을 유지할 수 있는 방법을 업데이트합니다.

ContextProvider 이제 HistoryProvider 정식 Python 기본 클래스입니다.
BaseContextProvider와 BaseHistoryProvider은 호환성을 위해 일시적으로 사용 중단된 별칭으로 남아있지만, 새 코드는 새 이름으로 이전되어야 합니다.
SessionContext 는 이제 공급자가 추가한 채팅 또는 함수 미들웨어를 extend_middleware() 하여 수집하고, 평면화된 목록을 통해 get_middleware()에 노출할 수 있습니다.
Agent(..., require_per_service_call_history_persistence=True) 는 전체 run() 후 한 번이 아니라 각 모델 호출 시 기록 공급자를 실행합니다.
이 모드는 프레임워크 관리 로컬 기록을 위한 것이며, 기존 서비스 관리 대화(예: session.service_session_id 또는 options={"conversation_id": ...})와 함께 사용할 수 없습니다.

Before:

from agent_framework import BaseHistoryProvider

class CustomHistoryProvider(BaseHistoryProvider):
    ...

After:

from agent_framework import Agent, HistoryProvider

class CustomHistoryProvider(HistoryProvider):
    ...

agent = Agent(
    client=client,
    context_providers=[CustomHistoryProvider()],
    require_per_service_call_history_persistence=True,
)

🔴 사용 중단된 Azure/OpenAI 호환성 인터페이스가 제거됨

PR:#4990

PR #4990 은 이전 미리 보기 릴리스 동안 사용 가능한 상태로 유지되었던 #4818의 모든 사용되지 않는 Python 호환성 영역을 제거함으로써 공급자를 선도하는 마이그레이션을 완료합니다.

agent_framework.azure는 더 이상 AzureOpenAI* 또는 이전 AzureAI* 에이전트/클라이언트/공급자 기능을 내보내지 않습니다.
Python OpenAI Assistants 호환성 유형은 더 이상 현재 agent_framework.openai 화면의 일부가 아닙니다.
다음과 같은 직접 OpenAI 또는 Azure OpenAI 시나리오에서 OpenAIChatClient, OpenAIChatCompletionClient, OpenAIEmbeddingClient를 사용하세요.
Foundry 프로젝트 추론에는 FoundryChatClient을, 프롬프트 에이전트나 HostedAgent에는 FoundryAgent을 사용하십시오.
현재 agent_framework.azure 네임스페이스는 이제 Azure AI 검색, Cosmos 기록, Azure Functions 및 지속성 워크플로와 같은 나머지 Azure 통합을 다룹니다. Foundry의 채팅, 에이전트, 메모리 및 임베딩 클라이언트는 agent_framework.foundry 아래에 위치해 있습니다.

이전 Python 코드를 마이그레이션하는 경우 다음 대체 항목을 사용합니다.

AzureOpenAIResponsesClient → OpenAIChatClient
AzureOpenAIChatClient → OpenAIChatCompletionClient
AzureOpenAIEmbeddingClient → OpenAIEmbeddingClient
AzureAIAgentClient / AzureAIClient / AzureAIProjectAgentProvider / AzureAIAgentsProvider FoundryChatClient 앱이 에이전트 정의를 소유하는지 여부에 따라 → 또는 FoundryAgent
OpenAIAssistantsClient / OpenAIAssistantProvider OpenAIChatClient 현재 Python OpenAI 작업에 대한 → 또는 FoundryAgent Foundry에서 서비스 관리 에이전트가 필요한 경우

🔴 공급자를 선도하는 클라이언트 디자인 및 패키지 분할

PR:#4818

PR #4818 은 공급자별 패키지 및 네임스페이스를 중심으로 Python 공급자 화면을 재구성합니다.

이제 OpenAI 클라이언트는 agent-framework-openai 패키지에 있으며, 여전히 agent_framework.openai 네임스페이스에서 가져옵니다.
이제 Microsoft Foundry 클라이언트는 agent-framework-foundry 패키지와 agent_framework.foundry 네임스페이스에 포함되어 있습니다.
Foundry Local은 agent_framework.foundry에서도 FoundryLocalClient로 노출됩니다.
OpenAIResponsesClient가 OpenAIChatClient으로 이름이 변경되었습니다.
OpenAIChatClient가 OpenAIChatCompletionClient으로 이름이 변경되었습니다.
클라이언트 구성은 표준화되어 model이전 매개 변수(예: , model_id및 deployment_name)를 model_deployment_name대체합니다.
새 Azure OpenAI 코드에는 agent_framework.openai 클라이언트를 사용하세요. 이전 AzureOpenAI* 호환성 레이어는 #4990에서 나중에 제거되었습니다.
새 Foundry 코드의 경우 FoundryChatClient는 직접 프로젝트 유추에, FoundryAgent는 프롬프트 에이전트 및 HostedAgents에, FoundryLocalClient는 로컬 런타임에 사용합니다.
AzureAIClient AzureAIProjectAgentProvider, AzureAIAgentClient, AzureAIAgentsProvider및 Python Assistants 호환성 화면은 이 리팩터링 중에 호환성 경로로 이동했으며 나중에 #4990에서 제거되었습니다.
아래의 Foundry 샘플을 포함하여 새 공급자 선행 레이아웃과 일치하도록 샘플 적용 범위가 재구성되었습니다 samples/02-agents/providers/foundry/.

패키지 매핑

Scenario	Install	기본 네임스페이스
OpenAI 및 Azure OpenAI	`pip install agent-framework-openai`	`agent_framework.openai`
Microsoft Foundry 프로젝트 엔드포인트, 에이전트 서비스, 메모리와 임베딩	`pip install agent-framework-foundry`	`agent_framework.foundry`
파운드리 로컬	`pip install agent-framework-foundry-local --pre`	`agent_framework.foundry`

Before:

from agent_framework.openai import OpenAIResponsesClient

client = OpenAIResponsesClient(model_id="gpt-5.4")

After:

from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient(model="gpt-5.4")

이전에 Azure OpenAI를 직접 사용한 경우 이전 전용 클래스를 새 공급자 선행 OpenAI 클래스에 매핑합니다.

AzureOpenAIResponsesClient → OpenAIChatClient
AzureOpenAIChatClient → OpenAIChatCompletionClient
AzureOpenAIEmbeddingClient → OpenAIEmbeddingClient
직접적인 Responses API 마이그레이션의 경우 AzureOpenAIAssistantsClient → OpenAIChatClient를 사용하고, 서비스 관리형 Foundry 에이전트가 필요한 경우 FoundryAgent를 사용하세요

코드 변경은 주로 클래스 이름 이동과 deployment_name → model. Azure OpenAI 호환성을 위해 새 OpenAI 클라이언트에서 명시적 Azure 입력을 사용합니다. credential= 는 이제 기본 설정 Azure 인증 화면이지만 호출 가능한 api_key 값은 호환성 경로로 유지됩니다.

이전(AzureOpenAIResponsesClient):

from agent_framework.azure import AzureOpenAIResponsesClient

client = AzureOpenAIResponsesClient(
    endpoint=azure_endpoint,
    deployment_name=deployment_name,
    credential=credential,
)

이후(OpenAIChatClient):

from agent_framework.openai import OpenAIChatClient
from azure.identity import AzureCliCredential

api_version = "your-azure-openai-api-version"

client = OpenAIChatClient(
    azure_endpoint=azure_endpoint,
    model=deployment_name,
    credential=AzureCliCredential(),
    api_version=api_version,
)

이전(AzureOpenAIChatClient):

from agent_framework.azure import AzureOpenAIChatClient

client = AzureOpenAIChatClient(
    endpoint=azure_endpoint,
    deployment_name=deployment_name,
    credential=credential,
)

이후(OpenAIChatCompletionClient):

from agent_framework.openai import OpenAIChatCompletionClient
from azure.identity import AzureCliCredential

api_version = "your-azure-openai-api-version"

client = OpenAIChatCompletionClient(
    azure_endpoint=azure_endpoint,
    model=deployment_name,
    credential=AzureCliCredential(),
    api_version=api_version,
)

Azure OpenAI 엔드포인트에서 Microsoft Foundry 프로젝트 엔드포인트로 이동하려면 Foundry 지향 표면을 대신 사용합니다.

이전(Azure OpenAI 엔드포인트):

from agent_framework.azure import AzureOpenAIResponsesClient
from azure.identity import AzureCliCredential

client = AzureOpenAIResponsesClient(
    deployment_name="gpt-4.1",
    credential=AzureCliCredential(),
)

변경 후 (Foundry 프로젝트):

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

client = FoundryChatClient(
    project_endpoint="https://your-project.services.ai.azure.com",
    model="gpt-4.1",
    credential=AzureCliCredential(),
)

agent = Agent(client=client)

로컬 Microsoft Foundry 런타임의 경우 Foundry 네임스페이스 및 로컬 커넥터를 사용합니다.

from agent_framework.foundry import FoundryLocalClient

client = FoundryLocalClient(model="phi-4-mini")

model를 생략하면, 사용자 환경에서 FOUNDRY_LOCAL_MODEL을(를) 설정하십시오.

또한 해당하는 경우 환경/구성 이름을 업데이트합니다.

OPENAI_CHAT_MODEL는 OpenAIChatClient에, OPENAI_CHAT_COMPLETION_MODEL는 OpenAIChatCompletionClient에 사용하고, OPENAI_MODEL는 공동으로 대체(fallback)로 사용합니다.
이제 Azure OpenAI는 AZURE_OPENAI_CHAT_MODEL을(를) OpenAIChatClient로 사용하고, AZURE_OPENAI_CHAT_COMPLETION_MODEL을(를) OpenAIChatCompletionClient로 사용하며, AZURE_OPENAI_MODEL을(를) 공유 대체로 사용합니다.
사용 중인 Azure OpenAI 리소스 URL에 azure_endpoint를 사용하십시오. 전체 base_url URL이 이미 있는 경우에는 .../openai/v1를 사용하고, 사용 중인 Azure OpenAI API의 특정 기능이나 영역에는 api_version를 설정하십시오.
Foundry 클라이언트를 위해 FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL, FOUNDRY_AGENT_NAME, 및 FOUNDRY_AGENT_VERSION와 같은 Foundry 관련 설정을 채택합니다.
Anthropic에 ANTHROPIC_CHAT_MODEL을(를), Foundry Local에 FOUNDRY_LOCAL_MODEL을(를) 사용하십시오.

이 변경은 python-1.0.0rc6 주기 동안에 처음으로 적용되었습니다.

🔴 이제 핵심 종속성이 의도적으로 슬림해졌습니다.

PR:#4904

PR #4904는 #4818의 공급자 패키지 분할을 따르며, agent-framework-core를 축소하고 핵심 패키지에서 더 많은 전이적 공급자 종속성을 제거합니다.

agent-framework-core 는 이제 의도적으로 최소화되어 있습니다.
agent_framework.openai를 가져오려면, agent-framework-openai을 설치하십시오.
agent_framework.foundry를 가져오는 경우, Foundry 프로젝트 추론, 서비스 관리형 에이전트, 메모리 공급자 및 임베딩을 위해 agent-framework-foundry를 설치하세요. 로컬 런타임에 agent-framework-foundry-local --pre를 사용하세요.
최소 설치에서 MCP 도구 Agent.as_mcp_server()또는 기타 MCP 통합을 사용하는 경우 수동으로 설치 mcp --pre 합니다. WebSocket MCP를 지원하려면 mcp[ws] --pre을(를) 설치하세요.
광범위한 "모든 항목 포함" 환경을 원하는 경우 메타 패키지를 agent-framework설치합니다.

이렇게 하면 공급자 화면이 다시 디자인 되지 않습니다 . 코어를 가져올 때만 기본적으로 설치되는 항목이 변경됩니다.

이전(코어 전용 설치는 더 많은 공급자 기능을 전이적으로 가져오는 경우가 많습니다).

pip install agent-framework-core

(실제로 사용하는 공급자 패키지를 설치) 후:

pip install agent-framework-core
pip install agent-framework-openai

or:

pip install agent-framework-core
pip install agent-framework-foundry

이전에 코어 및 지연 로딩 공급자 가져오기에 의존했던 기존 프로젝트를 업그레이드하는 경우 가져오기를 검토하고, 환경 또는 종속성 파일에서 공급자 패키지를 명시적으로 지정하십시오. MCP 도구 또는 MCP 서버 호스팅을 사용하는 경우 MCP 종속성에 대해 동일한 작업을 수행합니다.

🔴 일반 OpenAI 클라이언트는 이제 명시적 라우팅 신호를 선호합니다.

PR:#4925

PR #4925 은 일반 agent_framework.openai 클라이언트가 OpenAI와 Azure OpenAI 중에서 결정하는 방식을 변경합니다.

일반 OpenAI 클라이언트는 환경 변수가 존재하기 때문에 AZURE_OPENAI_* 더 이상 Azure로 전환되지 않습니다.
구성된 경우 OPENAI_API_KEY 일반 클라이언트는 명시적 Azure 라우팅 신호(예: credential 또는 azure_endpoint.)를 전달하지 않는 한 OpenAI에 유지됩니다.
AZURE_OPENAI_* 설정만 있는 경우, 일반 클라이언트는 여전히 Azure 환경 기반 라우팅으로 되돌아갈 수 있습니다.
이제 선호하는 Azure OpenAI 패턴은 명시적 Azure 설정과 credential=AzureCliCredential()을 OpenAIChatClient, OpenAIChatCompletionClient, 임베딩 클라이언트에 전달하는 것입니다.
사용되지 않는 래퍼는 AzureOpenAI* 호환성 동작을 유지하므로 기존 래퍼 기반 코드는 새 제네릭 클라이언트 우선 순위 규칙을 따르지 않습니다.

이전에는(OpenAIChatClient Azure env vars가 있었기 때문에 Azure로 라우팅할 수 있음):

import os
from agent_framework.openai import OpenAIChatClient

os.environ["OPENAI_API_KEY"] = "sk-openai"
os.environ["AZURE_OPENAI_ENDPOINT"] = "https://your-resource.openai.azure.com"
os.environ["AZURE_OPENAI_CHAT_MODEL"] = "gpt-4o-mini"

client = OpenAIChatClient(model="gpt-4o-mini")

이후(일반 OpenAI는 OpenAI에 유지되며, 명시적 Azure 입력을 전달하여 Azure 라우팅을 강제로 적용합니다.)

import os
from agent_framework.openai import OpenAIChatClient
from azure.identity import AzureCliCredential

client = OpenAIChatClient(
    model=os.environ["AZURE_OPENAI_CHAT_MODEL"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    credential=AzureCliCredential(),
)

환경에 OPENAI_* 및 AZURE_OPENAI_* 값이 모두 포함되어 있는 경우, agent_framework.openai 클라이언트의 일반적인 구성을 감사하고 공급자 선택을 명확히 지정합니다. 이러한 이유로 Azure 공급자 샘플이 Azure 입력을 직접 전달하도록 업데이트되었습니다.

이제 Azure 임베딩은 동일한 라우팅 모델을 따릅니다.

import os
from agent_framework.openai import OpenAIEmbeddingClient
from azure.identity import AzureCliCredential

client = OpenAIEmbeddingClient(
    model=os.environ["AZURE_OPENAI_EMBEDDING_MODEL"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    credential=AzureCliCredential(),
)

포함 시나리오의 경우 다음을 매핑합니다.

AzureOpenAIEmbeddingClient → OpenAIEmbeddingClient
AZURE_OPENAI_EMBEDDING_MODEL → model
OPENAI_EMBEDDING_MODEL 는 OpenAI 쪽 포함 환경 변수로 유지됩니다.

python-1.0.0rc5 / python-1.0.0b260319(2026년 3월 19일)

🔴 채팅 클라이언트 파이프라인 순서 변경: FunctionInvocation이 이제 ChatMiddleware를 래핑합니다.

PR:#4746

ChatClient 파이프라인 순서가 변경되었습니다. 이제 FunctionInvocation이 가장 바깥쪽 레이어가 되어 ChatMiddleware를 래핑합니다. 즉, 챗 미들웨어는 전체 함수 호출 시퀀스에 대해 한 번 실행되는 것이 아니라 모델 호출마다(도구 호출 루프의 각 반복 포함) 실행됩니다.

이전 파이프라인 순서:

ChatMiddleware → FunctionInvocation → RawChatClient

새 파이프라인 주문:

FunctionInvocation → ChatMiddleware → ChatTelemetry → RawChatClient

에이전트 호출당 한 번만 실행한다고 가정하는 사용자 지정 채팅 미들웨어가 있는 경우(전체 도구 호출 루프 래핑) 반복 실행에 안전하도록 업데이트합니다. 이제 도구 결과를 모델로 다시 보내는 요청을 포함하여 각 개별 LLM 요청에 대해 채팅 미들웨어가 호출됩니다.

또한 이제 ChatTelemetry는 파이프라인에서 ChatMiddleware와 분리된 별도의 레이어로 작동하며, RawChatClient에 가장 가깝게 실행됩니다.

🔴 공개 런타임 kwargs가 명시적 버킷으로 분할됨

PR:#4581

공용 Python 에이전트 및 채팅 API는 더 이상 일괄 공용 **kwargs 전달을 기본 런타임 데이터 메커니즘으로 처리하지 않습니다. 이제 런타임 값이 용도에 따라 분할됩니다.

function_invocation_kwargs는 도구 또는 함수 미들웨어만 볼 수 있는 값에 사용하십시오.
client_kwargs를 클라이언트 계층 kwargs 및 클라이언트 미들웨어 구성에 사용하세요.
FunctionInvocationContext (ctx.kwargs 및 ctx.session)를 통해 도구/런타임 데이터에 액세스합니다.
**kwargs 대신 삽입된 컨텍스트 매개 변수를 사용하여 도구를 정의합니다. 삽입된 컨텍스트 매개 변수는 모델이 보는 스키마에 표시되지 않습니다.
하위 에이전트를 도구로 위임할 때, 자식 에이전트가 호출자의 세션을 공유해야 하는 경우에는 agent.as_tool(propagate_session=True)을 사용합니다.

Before:

from typing import Any

from agent_framework import tool


@tool
def send_email(address: str, **kwargs: Any) -> str:
    return f"Queued email for {kwargs['user_id']}"


response = await agent.run(
    "Send the update to finance@example.com",
    user_id="user-123",
    request_id="req-789",
)

After:

from agent_framework import FunctionInvocationContext, tool


@tool
def send_email(address: str, ctx: FunctionInvocationContext) -> str:
    user_id = ctx.kwargs["user_id"]
    session_id = ctx.session.session_id if ctx.session else "no-session"
    return f"Queued email for {user_id} in {session_id}"


response = await agent.run(
    "Send the update to finance@example.com",
    session=agent.create_session(),
    function_invocation_kwargs={
        "user_id": "user-123",
        "request_id": "req-789",
    },
)

사용자 지정 공용 run() 또는 get_response() 메서드를 구현하는 경우 해당 서명에 function_invocation_kwargs 및 client_kwargs을(를) 추가하십시오. 도구의 경우, 주석이 추가된 FunctionInvocationContext 매개변수를 선호합니다. ctx, context, 또는 주석된 다른 이름을 사용할 수도 있습니다. 명시적 스키마/입력 모델을 제공하는 경우 명명 ctx 된 주석이 지정되지 않은 일반 매개 변수도 인식됩니다. 동일한 컨텍스트 개체를 함수 미들웨어에 사용할 수 있으며 런타임 함수 kwargs 및 세션 상태가 현재 있는 위치입니다. **kwargs에 의존하는 도구 정의는 레거시 호환 경로만 사용하며 곧 제거될 것입니다.

python-1.0.0rc4 / python-1.0.0b260311(2026년 3월 11일)

릴리스 정보:python-1.0.0rc4

🔴 Azure AI 통합은 이제 2.0 GA를 대상으로 `azure-ai-projects` 합니다.

PR:#4536

이제 Python Azure AI 통합은 GA 2.0 azure-ai-projects 표면을 가정합니다.

이제 azure-ai-projects>=2.0.0,<3.0지원되는 종속성 범위가 있습니다.
foundry_features 패스스루가 Azure AI 에이전트 생성에서 제거되었습니다.
미리 보기 동작이 이제 allow_preview=True를 지원되는 클라이언트/공급자에서 사용합니다.
혼합 베타/GA 호환성 심(shim)이 제거되었으므로, 모든 가져오기 및 유형 이름을 2.0 GA SDK 표면으로 업데이트하세요.

🔴 GitHub Copilot 도구 처리기는 이제 `ToolInvocation` / `ToolResult` 및 Python 3.11 이상을 사용합니다.

PR:#4551

agent-framework-github-copilot 이제 github-copilot-sdk>=0.1.32를 추적합니다.

도구 처리기는 원시 dict가 아닌 ToolInvocation 데이터 클래스를 받습니다.
result_type 및 text_result_for_llm 같은 snake_case 필드를 사용하여 ToolResult를 반환합니다.
이제 패키지에 agent-framework-github-copilot Python 3.11 이상이 필요합니다.

Before:

from typing import Any


def handle_tool(invocation: dict[str, Any]) -> dict[str, Any]:
    args = invocation.get("arguments", {})
    return {
        "resultType": "success",
        "textResultForLlm": f"Handled {args.get('city', 'request')}",
    }

After:

from copilot.tools import ToolInvocation, ToolResult


def handle_tool(invocation: ToolInvocation) -> ToolResult:
    args = invocation.arguments
    return ToolResult(
        result_type="success",
        text_result_for_llm=f"Handled {args.get('city', 'request')}",
    )

python-1.0.0rc3 / python-1.0.0b260304(2026년 3월 4일)

릴리스 정보:python-1.0.0rc3

🔴 코드 정의에 따라 기술 공급자가 최종 결정됨 `Skill` / `SkillResource`

PR:#4387

이제 Python 에이전트 기술은 파일 기반 기술과 함께 코드 정의 Skill 및 SkillResource 개체를 지원하며, 공용 공급자 인터페이스는 SkillsProvider로 표준화되었습니다.

이전 미리 보기/내부 FileAgentSkillsProvider를 계속 가져오는 경우, SkillsProvider로 전환하십시오.
파일 기반 리소스 조회는 더 이상 SKILL.md의 백틱으로 묶인 참조에 의존하지 않으며, 대신 스킬 디렉터리에서 리소스를 탐색합니다.

FileAgentSkillsProvider을(를) 가져오는 미리 보기/내부 코드를 사용했던 경우, 현재 공용 API로 전환하세요.

from agent_framework import Skill, SkillResource, SkillsProvider

python-1.0.0rc2 / python-1.0.0b260226(2026년 2월 26일)

릴리스 정보:python-1.0.0rc2

🔴 선언적 워크플로가 `InvokeTool`을 `InvokeFunctionTool`로 대체합니다.

PR:#3716

선언적 Python 워크플로는 더 이상 이전 InvokeTool 작업 종류를 사용하지 않습니다. InvokeFunctionTool로 교체하고 Python 호출 가능 항목을 WorkflowFactory.register_tool()에 등록합니다.

Before:

actions:
  - kind: InvokeTool
    toolName: send_email

After:

factory = WorkflowFactory().register_tool("send_email", send_email)

actions:
  - kind: InvokeFunctionTool
    functionName: send_email

python-1.0.0rc1 / python-1.0.0b260219(2026년 2월 19일)

릴리스:agent-framework-coreagent-framework-azure-ai가 1.0.0rc1로 승격되었습니다. 모든 패키지가 1.0.0b260219로 업데이트되었습니다.

🔴 모든 패키지에서 통합 Azure 자격 증명 처리

PR:#4088

ad_token, ad_token_provider및 get_entra_auth_token 매개 변수/도우미가 모든 Azure 관련 Python 패키지에서 통합 credential 매개 변수로 대체되었습니다. 새 방법은 자동 토큰 캐싱 및 새로 고침에 사용됩니다 azure.identity.get_bearer_token_provider .

영향을 받는 클래스:AzureOpenAIChatClient, ,AzureOpenAIResponsesClientAzureOpenAIAssistantsClient, AzureAIClient, AzureAIAgentClient, AzureAIProjectAgentProviderAzureAIAgentsProvider, AzureAISearchContextProviderPurviewClient, . PurviewPolicyMiddlewarePurviewChatPolicyMiddleware

Before:

from azure.identity import AzureCliCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    AzureCliCredential(), "https://cognitiveservices.azure.com/.default"
)

client = AzureOpenAIResponsesClient(
    azure_ad_token_provider=token_provider,
    ...
)

After:

from azure.identity import AzureCliCredential

client = AzureOpenAIResponsesClient(
    credential=AzureCliCredential(),
    ...
)

매개 변수는 credential, TokenCredential 또는 호출 가능한 토큰 공급자를 허용합니다. 토큰 캐싱 및 새로 고침은 자동으로 처리됩니다.

🔴 다시 디자인된 Python 예외 계층 구조

PR:#4082

플랫 ServiceException 패밀리가 단일 AgentFrameworkException 루트 아래의 도메인 범위 예외 분기로 대체되었습니다. 이렇게 하면 호출자에게 정확한 except 대상과 명확한 오류 의미 체계를 제공합니다.

새 계층 구조:

AgentFrameworkException
├── AgentException
│   ├── AgentInvalidAuthException
│   ├── AgentInvalidRequestException
│   ├── AgentInvalidResponseException
│   └── AgentContentFilterException
├── ChatClientException
│   ├── ChatClientInvalidAuthException
│   ├── ChatClientInvalidRequestException
│   ├── ChatClientInvalidResponseException
│   └── ChatClientContentFilterException
├── IntegrationException
│   ├── IntegrationInitializationError
│   ├── IntegrationInvalidAuthException
│   ├── IntegrationInvalidRequestException
│   ├── IntegrationInvalidResponseException
│   └── IntegrationContentFilterException
├── ContentError
├── WorkflowException
│   ├── WorkflowRunnerException
│   ├── WorkflowValidationError
│   └── WorkflowActionError
├── ToolExecutionException
├── MiddlewareTermination
└── SettingNotFoundError

예외 제거:ServiceException, , ServiceInitializationError, ServiceResponseExceptionServiceContentFilterException, ServiceInvalidAuthError, ServiceInvalidExecutionSettingsErrorServiceInvalidRequestError, ServiceInvalidResponseError, AgentExecutionExceptionAgentInvocationErrorAgentInitializationError, . AgentSessionExceptionChatClientInitializationErrorCheckpointDecodingError

Before:

from agent_framework.exceptions import ServiceException, ServiceResponseException

try:
    result = await agent.run("Hello")
except ServiceResponseException:
    ...
except ServiceException:
    ...

After:

from agent_framework.exceptions import AgentException, AgentInvalidResponseException, AgentFrameworkException

try:
    result = await agent.run("Hello")
except AgentInvalidResponseException:
    ...
except AgentException:
    ...
except AgentFrameworkException:
    # catch-all for any Agent Framework error
    ...

비고

이제 Init 유효성 검사 오류는 사용자 지정 예외 대신 기본 제공 ValueError/TypeError 을 사용합니다. 에이전트 프레임워크 예외는 도메인 수준 오류에 대해 예약됩니다.

🔴 공급자 상태를 범위로 지정 `source_id`

PR:#3995

이제 공급자 후크는 전체 세션 상태 대신 공급자 범위 상태 사전(state.setdefault(provider.source_id, {}))을 받습니다. 즉, 이전에 state[self.source_id]["key"]를 통해 중첩된 상태에 액세스하던 공급자 구현은 이제 state["key"]에 직접 액세스해야 합니다.

또한 InMemoryHistoryProvider 기본값이 source_id에서 "memory""in_memory"로 변경되었습니다.

Before:

# In a custom provider hook:
async def on_before_agent(self, state: dict, **kwargs):
    my_data = state[self.source_id]["my_key"]

# InMemoryHistoryProvider default source_id
provider = InMemoryHistoryProvider("memory")

After:

# Provider hooks receive scoped state — no nested access needed:
async def on_before_agent(self, state: dict, **kwargs):
    my_data = state["my_key"]

# InMemoryHistoryProvider default source_id changed
provider = InMemoryHistoryProvider("in_memory")

🔴 채팅/에이전트 메시지 입력 맞춤(`run` vs `get_response`)

PR:#3920

이제 채팅 클라이언트 get_response 구현은 Sequence[Message]을 일관되게 수신합니다. agent.run(...)은(는) 유연하게 유지되고(strContentMessage해당 시퀀스) 채팅 클라이언트를 호출하기 전에 입력을 정규화합니다.

Before:

async def get_response(self, messages: str | Message | list[Message], **kwargs): ...

After:

from collections.abc import Sequence
from agent_framework import Message

async def get_response(self, messages: Sequence[Message], **kwargs): ...

🔴 `FunctionTool[Any]` 스키마 통과를 위해 제네릭 설정이 제거됨

PR:#3907

스키마 기반 도구 경로는 더 이상 이전 FunctionTool[Any] 의 제네릭 동작을 사용하지 않습니다. FunctionTool를 직접 사용하고, 필요한 경우 @tool(schema=...)를 사용하여 pydantic BaseModel 또는 명시적 스키마를 제공합니다.

Before:

placeholder: FunctionTool[Any] = FunctionTool(...)

After:

placeholder: FunctionTool = FunctionTool(...)

🔴 Pydantic 설정으로 대체됨 `TypedDict` + `load_settings()`

PR:#3843, #4032

pydantic-settings-기반의 AFBaseSettings 클래스는 TypedDict와 load_settings()를 사용한 경량의 함수 기반 설정 시스템으로 대체되었습니다. pydantic-settings 종속성이 완전히 제거되었습니다.

이제 모든 설정 클래스(예: OpenAISettings, AzureOpenAISettings, AnthropicSettings)는 TypedDict 정의로 간주되며, 설정 값은 속성 접근 대신 딕셔너리 구문을 통해 액세스됩니다.

Before:

from agent_framework.openai import OpenAISettings

settings = OpenAISettings()  # pydantic-settings auto-loads from env
api_key = settings.api_key
model_id = settings.model_id

After:

from agent_framework import load_settings
from agent_framework.openai import OpenAISettings

settings = load_settings(OpenAISettings, env_prefix="OPENAI_")
api_key = settings["api_key"]
model = settings["model"]

중요합니다

에이전트 프레임워크는 파일에서 값을 자동으로 로드.env 않습니다. 다음 중 하나를 선택하여 .env 로드를 명시적으로 허용해야 합니다.

애플리케이션 시작 시 load_dotenv() 패키지에서 python-dotenv를 호출
env_file_path=".env"를 load_settings()로 전달하기
셸 또는 IDE에서 직접 환경 변수 설정

load_settings 확인 순서: 명시적 재정의 → .env 파일 값 (env_file_path가 제공된 경우) → 환경 변수 → 기본값. env_file_path를 지정하는 경우, 파일이 존재해야 하며 그렇지 않으면 FileNotFoundError가 발생합니다.

🟡 추론 모델 워크플로 이양 및 기록 직렬화 수정

PR:#4083

다중 에이전트 워크플로에서 추론 모델(예: gpt-5-mini, gpt-5.2)을 사용할 때 여러 오류를 수정합니다. 응답 API의 추론 항목은 이제 올바르게 직렬화되며, function_call가 있을 때에만 기록에 포함되어 API 오류를 방지합니다. 이제 암호화/숨겨진 추론 콘텐츠가 제대로 내보내지고 필드 형식이 summary 수정됩니다. service_session_id 또한 에이전트 간 상태 누출을 방지하기 위해 인계 시 지워집니다.

🟡 Bedrock이 `core[all]`에 추가되었고 도구 선택 기본값이 수정됨

PR:#3953

아마존 베드록은 이제 agent-framework-core[all] 추가 기능에 포함되어 있으며 agent_framework.amazon 레이지 임포트 인터페이스를 통해 사용할 수 있습니다. 도구 선택 동작도 수정되었습니다. 설정되지 않은 도구 선택 값은 이제 설정되지 않은 상태로 유지되므로 공급자는 서비스 기본값을 사용하고 명시적으로 설정된 값은 유지됩니다.

from agent_framework.amazon import BedrockChatClient

🟡 지원되지 않는 런타임 재정의에 대한 AzureAIClient 경고

PR:#3919

이 변경 시 AzureAIClient가 런타임 tools 또는 structured_output가 에이전트의 생성 시 구성과 다를 때 경고를 기록했습니다. 이후 Python 표면이 제거되었습니다. 현재 Python 코드의 경우, 앱 소유 도구/런타임 구성이 필요할 때는 FoundryChatClient을(를) 사용하고, 동적 재정이가 필요한 직접 응답 API 시나리오에는 OpenAIChatClient을(를) 사용하십시오.

🟡 `workflow.as_agent()` 이제 공급자가 설정되지 않은 경우 로컬 기록이 기본값으로 설정됩니다.

PR:#3918

workflow.as_agent()가 context_providers 없이 생성될 때, 기본적으로 InMemoryHistoryProvider("memory")가 추가됩니다. 컨텍스트 공급자가 명시적으로 제공된 경우 해당 목록은 변경되지 않고 유지됩니다.

workflow_agent = workflow.as_agent(name="MyWorkflowAgent")
# Default local history provider is injected when none are provided.

🟡 MCP 요청에 전파된 OpenTelemetry 추적 컨텍스트

PR:#3780

OpenTelemetry가 설치되면 추적 컨텍스트(예: W3C traceparent)가 을 통해 params._metaMCP 요청에 자동으로 삽입됩니다. 이렇게 하면 에이전트 → MCP 서버 호출에서 엔드투엔드 분산 추적이 가능합니다. 코드 변경이 필요하지 않습니다. 유효한 범위 컨텍스트가 있을 때 활성화되는 추가 동작입니다.

🟡 Azure Functions에 대한 지속성 워크플로 지원

PR:#3630

패키지에서는 이제 Azure Durable Functions에서 agent-framework-azurefunctions 그래프를 실행할 수 있습니다. 매개 변수를 workflow 전달하여 AgentFunctionApp 에이전트 엔터티, 활동 함수 및 HTTP 엔드포인트를 자동으로 등록합니다.

from agent_framework.azure import AgentFunctionApp

app = AgentFunctionApp(workflow=my_workflow)
# Automatically registers:
#   POST /api/workflow/run          — start a workflow
#   GET  /api/workflow/status/{id}  — check status
#   POST /api/workflow/respond/{id}/{requestId} — HITL response

구성 가능한 시간 제한 및 만료 시 자동 거부를 사용하여 팬아웃/팬인, 공유 상태 및 휴먼 인 더 루프 패턴을 지원합니다.

python-1.0.0b260212(2026년 2월 12일)

릴리스 정보:python-1.0.0b260212

🔴 `HostedTool` 클래스가 클라이언트 `get__tool()` 메서드로 대체됨

PR:#3634

클라이언트 범위 팩터리 메서드를 선호하여 호스트된 도구 클래스가 제거되었습니다. 이렇게 하면 공급자가 도구 가용성을 명시적으로 설정합니다.

제거된 클래스	교체
`HostedCodeInterpreterTool`	`client.get_code_interpreter_tool()`
`HostedWebSearchTool`	`client.get_web_search_tool()`
`HostedFileSearchTool`	`client.get_file_search_tool(...)`
`HostedMCPTool`	`client.get_mcp_tool(...)`
`HostedImageGenerationTool`	`client.get_image_generation_tool(...)`

Before:

from agent_framework import HostedCodeInterpreterTool, HostedWebSearchTool

tools = [HostedCodeInterpreterTool(), HostedWebSearchTool()]

After:

from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient()
tools = [client.get_code_interpreter_tool(), client.get_web_search_tool()]

🔴 세션/컨텍스트 공급자 파이프라인 완료됨(`AgentSession`, `context_providers`)

PR:#3850

Python 세션 및 컨텍스트 공급자 마이그레이션이 완료되었습니다. AgentThread 이전 컨텍스트 공급자 형식이 제거되었습니다.

AgentThread → AgentSession
agent.get_new_thread() → agent.create_session()
agent.get_new_thread(service_thread_id=...) → agent.get_session(service_session_id=...)
context_provider= / chat_message_store_factory= 패턴이 다음으로 바뀝니다. context_providers=[...]
ChatMessageStore 가 제거되었습니다. 둘 다 agent_framework에서 내보내어지는 HistoryProvider (또는 기본 인메모리 케이스의 경우 InMemoryHistoryProvider)를 사용하세요. 컨텍스트 제공자가 전달되지 않으면 에이전트가 InMemoryHistoryProvider를 자동으로 삽입합니다.

Before:

thread = agent.get_new_thread()
response = await agent.run("Hello", thread=thread)

After:

session = agent.create_session()
response = await agent.run("Hello", session=session)

🔴 검사점 모델 및 스토리지 동작 리팩터링됨

PR:#3744

검사점 내부가 다시 디자인되어 지속형 검사점 호환성 및 사용자 지정 스토리지 구현에 영향을 줍니다.

WorkflowCheckpoint 이제 실시간 객체를 저장합니다(serialization은 체크포인트 스토리지에서 발생)
FileCheckpointStorage 이제 pickle serialization을 사용합니다.
workflow_id가 제거되고 추가되었습니다.previous_checkpoint_id
사용되지 않는 검사점 후크가 제거되었습니다.

버전 간에 검사점을 유지하는 경우 워크플로를 다시 시작하기 전에 기존 검사점 아티팩트 다시 생성 또는 마이그레이션합니다.

처음에 `AzureOpenAIResponsesClient`를 통해 나타난 🟡 Foundry 프로젝트의 엔드포인트

PR:#3814

이 미리 보기 기능은 원래 AzureOpenAIResponsesClient이 Foundry 프로젝트 엔드포인트에 연결할 수 있도록 허용되었습니다. 현재 Python 지침에서는 제거된 FoundryChatClient 대신, FoundryAgent를 Foundry 프로젝트 추론에, AzureOpenAIResponsesClient를 서비스 관리 Foundry 에이전트에 사용합니다.

from azure.identity import DefaultAzureCredential
from agent_framework.foundry import FoundryChatClient

client = FoundryChatClient(
    project_endpoint="https://<your-project>.services.ai.azure.com",
    model="gpt-4o-mini",
    credential=DefaultAzureCredential(),
)

🔴 미들웨어 `call_next` 가 더 이상 수락하지 않음 `context`

PR:#3829

미들웨어 연속성은 이제 인수를 받지 않습니다. 미들웨어가 call_next(context)를 여전히 호출하는 경우 call_next()로 업데이트합니다.

Before:

async def telemetry_middleware(context, call_next):
    # ...
    return await call_next(context)

After:

async def telemetry_middleware(context, call_next):
    # ...
    return await call_next()

python-1.0.0b260210(2026년 2월 10일)

릴리스 정보:python-1.0.0b260210

🔴 워크플로 팩터리 메서드가 제거됨 `WorkflowBuilder`

PR:#3781

register_executor()에서 register_agent() 및 WorkflowBuilder가 제거되었습니다. 모든 작성기 메서드(add_edge, , add_fan_out_edgesadd_fan_in_edges, add_chain, add_switch_case_edge_groupadd_multi_selection_edge_group) 및 start_executor 더 이상 문자열 이름을 허용하지 않습니다. 실행기 또는 에이전트 인스턴스가 직접 필요합니다.

상태 격리의 경우 각 호출이 새 인스턴스를 생성하도록 도우미 메서드 내에 실행기/에이전트 인스턴스화 및 워크플로 빌드를 래핑합니다.

실행기를 포함한 `WorkflowBuilder`

Before:

workflow = (
    WorkflowBuilder(start_executor="UpperCase")
    .register_executor(lambda: UpperCaseExecutor(id="upper"), name="UpperCase")
    .register_executor(lambda: ReverseExecutor(id="reverse"), name="Reverse")
    .add_edge("UpperCase", "Reverse")
    .build()
)

After:

upper = UpperCaseExecutor(id="upper")
reverse = ReverseExecutor(id="reverse")

workflow = WorkflowBuilder(start_executor=upper).add_edge(upper, reverse).build()

`WorkflowBuilder` 에이전트가 있는 경우

Before:

builder = WorkflowBuilder(start_executor="writer_agent")
builder.register_agent(factory_func=create_writer_agent, name="writer_agent")
builder.register_agent(factory_func=create_reviewer_agent, name="reviewer_agent")
builder.add_edge("writer_agent", "reviewer_agent")

workflow = builder.build()

After:

writer_agent = create_writer_agent()
reviewer_agent = create_reviewer_agent()

workflow = WorkflowBuilder(start_executor=writer_agent).add_edge(writer_agent, reviewer_agent).build()

도우미 메서드를 사용하여 상태 격리

호출마다 격리된 상태가 필요한 워크플로의 경우, 헬퍼 메서드 안에 생성 과정을 래핑하세요.

def create_workflow() -> Workflow:
    """Each call produces fresh executor instances with independent state."""
    upper = UpperCaseExecutor(id="upper")
    reverse = ReverseExecutor(id="reverse")

    return WorkflowBuilder(start_executor=upper).add_edge(upper, reverse).build()

workflow_a = create_workflow()
workflow_b = create_workflow()

<><> 이름이 <>로 변경되고, <> 이름이 <>로 변경됨.

PR:#3747

핵심 Python 형식은 중복 Chat 접두사를 제거하여 간소화되었습니다. 이전 버전과의 호환성 별칭은 제공되지 않습니다.

이전	이후
`ChatAgent`	`Agent`
`RawChatAgent`	`RawAgent`
`ChatMessage`	`Message`
`ChatClientProtocol`	`SupportsChatGetResponse`

임포트 업데이트

Before:

from agent_framework import ChatAgent, ChatMessage

After:

from agent_framework import Agent, Message

형식 참조 업데이트

Before:

agent = ChatAgent(
    chat_client=client,
    name="assistant",
    instructions="You are a helpful assistant.",
)

message = ChatMessage(role="user", contents=[Content.from_text("Hello")])

After:

agent = Agent(
    client=client,
    name="assistant",
    instructions="You are a helpful assistant.",
)

message = Message(role="user", contents=[Content.from_text("Hello")])

비고

ChatClient이 ChatResponseChatOptions 변경으로 이름이 바뀌지 않습니다.

🔴 형식 API는 응답/메시지 모델에서 업데이트를 검토합니다.

PR:#3647

이번 릴리스에는 메시지/응답 유형 지정 및 헬퍼 API에 대한 광범위한 파괴적 정리 작업이 포함되어 있습니다.

이제 Role 및 FinishReason는 알려진 값에 대해 RoleLiteral/FinishReasonLiteral을 사용하는 str 기반의 NewType 래퍼입니다. 문자열로 처리합니다(.value는 사용하지 마세요).
Message 구축은 Message(role, contents=[...])에 표준화됩니다. contents에 있는 문자열은 텍스트 콘텐츠로 자동 변환됩니다.
ChatResponse 및 AgentResponse 생성자는 이제 messages= (단일 Message 또는 시퀀스)를 중심으로 하고, 레거시 text= 생성자의 사용이 응답에서 제거되었습니다.
ChatResponseUpdate 및 AgentResponseUpdate는 이제 text=를 수락하지 않습니다. 대신 contents=[Content.from_text(...)]를 사용하십시오.
업데이트 결합 도우미 이름이 간소화되었습니다.
try_parse_value가 ChatResponse 및 AgentResponse에서 제거되었습니다.

도우미 메서드 이름 바꾸기

이전	이후
`ChatResponse.from_chat_response_updates(...)`	`ChatResponse.from_updates(...)`
`ChatResponse.from_chat_response_generator(...)`	`ChatResponse.from_update_generator(...)`
`AgentResponse.from_agent_run_response_updates(...)`	`AgentResponse.from_updates(...)`

응답 업데이트 구성 업데이트

Before:

update = AgentResponseUpdate(text="Processing...", role="assistant")

After:

from agent_framework import AgentResponseUpdate, Content

update = AgentResponseUpdate(
    contents=[Content.from_text("Processing...")],
    role="assistant",
)

`try_parse_value`에서 `try/except`를 `.value`로 교체하십시오.

Before:

if parsed := response.try_parse_value(MySchema):
    print(parsed.name)

After:

from pydantic import ValidationError

try:
    parsed = response.value
    if parsed:
        print(parsed.name)
except ValidationError as err:
    print(f"Validation failed: {err}")

🔴 `run` / `get_response` 통합 모델 및 `ResponseStream` 사용

PR:#3379

Python API는 agent.run(...) 및 client.get_response(...)를 중심으로 통합되었으며, 스트리밍은 ResponseStream로 표현됩니다.

Before:

async for update in agent.run_stream("Hello"):
    print(update)

After:

stream = agent.run("Hello", stream=True)
async for update in stream:
    print(update)

🔴 핵심 컨텍스트/프로토콜 형식 이름 바꾸기

PR:#3714, #3717

이전	이후
`AgentRunContext`	`AgentContext`
`AgentProtocol`	`SupportsAgentRun`

그에 따라 가져오기 및 형식 주석을 업데이트합니다.

🔴 미들웨어 연속 매개 변수 이름이 `call_next`로 변경됨 `call_next`

PR:#3735

이제 미들웨어 서명에는 call_next를 사용해야 하며, next 대신 사용합니다.

Before:

async def my_middleware(context, next):
    return await next(context)

After:

async def my_middleware(context, call_next):
    return await call_next(context)

🔴 표준화된 TypeVar 이름(`TName` → `NameT`)

PR:#3770

이제 코드베이스는 접미사가 T 사용되는 일관된 TypeVar 명명 스타일을 따릅니다.

Before:

TMessage = TypeVar("TMessage")

After:

MessageT = TypeVar("MessageT")

프레임워크 제네릭을 중심으로 사용자 지정 래퍼를 유지 관리하는 경우 주석 변동을 줄이기 위해 로컬 TypeVar 이름을 새 규칙에 맞춥니다.

🔴 워크플로 에이전트의 출력 및 스트리밍 변경 내용

PR:#3649

workflow.as_agent() 동작이 표준 에이전트 응답 패턴에 맞게 출력 및 스트리밍을 조정하도록 업데이트되었습니다. 레거시 출력/업데이트 처리에 의존하는 워크플로-에이전트 소비자를 검토하고 현재 AgentResponse/AgentResponseUpdate 흐름으로 업데이트합니다.

🔴 흐름 작성기 메서드가 생성자 매개 변수로 이동됨

PR:#3693

6개 작성기(WorkflowBuilder, , SequentialBuilder, ConcurrentBuilderGroupChatBuilder, MagenticBuilderHandoffBuilder)의 단일 구성 흐름 메서드가 생성자 매개 변수로 마이그레이션되었습니다. 설정의 유일한 구성 경로인 Fluent 메서드는 생성자 인수를 위해 제거됩니다.

`WorkflowBuilder`

set_start_executor(), with_checkpointing()및 with_output_from() 제거됩니다. 대신 생성자 매개 변수를 사용합니다.

Before:

upper = UpperCaseExecutor(id="upper")
reverse = ReverseExecutor(id="reverse")

workflow = (
    WorkflowBuilder(start_executor=upper)
    .add_edge(upper, reverse)
    .set_start_executor(upper)
    .with_checkpointing(storage)
    .build()
)

After:

upper = UpperCaseExecutor(id="upper")
reverse = ReverseExecutor(id="reverse")

workflow = (
    WorkflowBuilder(start_executor=upper, checkpoint_storage=storage)
    .add_edge(upper, reverse)
    .build()
)

`SequentialBuilder` / `ConcurrentBuilder`

participants(), register_participants(), with_checkpointing()및 with_intermediate_outputs() 제거됩니다. 대신 생성자 매개 변수를 사용합니다.

Before:

workflow = SequentialBuilder().participants([agent_a, agent_b]).with_checkpointing(storage).build()

After:

workflow = SequentialBuilder(participants=[agent_a, agent_b], checkpoint_storage=storage).build()

`GroupChatBuilder`

participants(), register_participants(), with_orchestrator(), with_termination_condition()with_max_rounds(), with_checkpointing()및 with_intermediate_outputs() 제거됩니다. 대신 생성자 매개 변수를 사용합니다.

Before:

workflow = (
    GroupChatBuilder()
    .with_orchestrator(selection_func=selector)
    .participants([agent1, agent2])
    .with_termination_condition(lambda conv: len(conv) >= 4)
    .with_max_rounds(10)
    .build()
)

After:

workflow = GroupChatBuilder(
    participants=[agent1, agent2],
    selection_func=selector,
    termination_condition=lambda conv: len(conv) >= 4,
    max_rounds=10,
).build()

`MagenticBuilder`

participants(), register_participants(), with_manager(), with_plan_review()with_checkpointing()및 with_intermediate_outputs() 제거됩니다. 대신 생성자 매개 변수를 사용합니다.

Before:

workflow = (
    MagenticBuilder()
    .participants([researcher, coder])
    .with_manager(agent=manager_agent)
    .with_plan_review()
    .build()
)

After:

workflow = MagenticBuilder(
    participants=[researcher, coder],
    manager_agent=manager_agent,
    enable_plan_review=True,
).build()

`HandoffBuilder`

with_checkpointing()와 with_termination_condition()가 제거됩니다. 대신 생성자 매개 변수를 사용합니다.

Before:

workflow = (
    HandoffBuilder(participants=[triage, specialist])
    .with_start_agent(triage)
    .with_termination_condition(lambda conv: len(conv) > 5)
    .with_checkpointing(storage)
    .build()
)

After:

workflow = (
    HandoffBuilder(
        participants=[triage, specialist],
        termination_condition=lambda conv: len(conv) > 5,
        checkpoint_storage=storage,
    )
    .with_start_agent(triage)
    .build()
)

유효성 검사 변경 내용

WorkflowBuilder 이제 생성자 인수로 필요합니다 start_executor (이전에 Fluent 메서드를 통해 설정됨).
SequentialBuilder, ConcurrentBuilder, GroupChatBuilder 및 MagenticBuilder는 이제 생성 시 participants 또는 participant_factories가 필요합니다 — 둘 중 아무것도 전달되지 않으면 ValueError가 발생합니다.

비고

HandoffBuilder 이미 생성자 매개 변수로 허용 participants/participant_factories 되었으며 이와 관련하여 변경되지 않았습니다.

🔴 워크플로 이벤트가 `WorkflowEvent` 판별자를 사용하여 단일 `type`로 통합됨

PR:#3690

모든 개별 워크플로 이벤트 서브클래스는 단일 제네릭 WorkflowEvent[DataT] 클래스로 대체되었습니다. 이제 isinstance() 검사를 사용하여 이벤트 유형을 식별하는 대신 event.type, "output", "request_info"와 같은 문자열 리터럴을 확인합니다. 이는 Content의 클래스 통합python-1.0.0b260123과 동일한 패턴을 따릅니다.

제거된 이벤트 클래스

내보낸 다음 이벤트 서브클래스가 더 이상 존재하지 않습니다.

이전 클래스	새 `event.type` 값
`WorkflowOutputEvent`	`"output"`
`RequestInfoEvent`	`"request_info"`
`WorkflowStatusEvent`	`"status"`
`WorkflowStartedEvent`	`"started"`
`WorkflowFailedEvent`	`"failed"`
`ExecutorInvokedEvent`	`"executor_invoked"`
`ExecutorCompletedEvent`	`"executor_completed"`
`ExecutorFailedEvent`	`"executor_failed"`
`SuperStepStartedEvent`	`"superstep_started"`
`SuperStepCompletedEvent`	`"superstep_completed"`

임포트 업데이트

Before:

from agent_framework import (
    WorkflowOutputEvent,
    RequestInfoEvent,
    WorkflowStatusEvent,
    ExecutorCompletedEvent,
)

After:

from agent_framework import WorkflowEvent
# Individual event classes no longer exist; use event.type to discriminate

이벤트 유형 검사 업데이트

Before:

async for event in workflow.run(input_message, stream=True):
    if isinstance(event, WorkflowOutputEvent):
        print(f"Output from {event.executor_id}: {event.data}")
    elif isinstance(event, RequestInfoEvent):
        requests[event.request_id] = event.data
    elif isinstance(event, WorkflowStatusEvent):
        print(f"Status: {event.state}")

After:

async for event in workflow.run(input_message, stream=True):
    if event.type == "output":
        print(f"Output from {event.executor_id}: {event.data}")
    elif event.type == "request_info":
        requests[event.request_id] = event.data
    elif event.type == "status":
        print(f"Status: {event.state}")

`AgentResponseUpdate`를 사용하여 스트리밍

Before:

from agent_framework import AgentResponseUpdate, WorkflowOutputEvent

async for event in workflow.run_stream("Write a blog post about AI agents."):
    if isinstance(event, WorkflowOutputEvent) and isinstance(event.data, AgentResponseUpdate):
        print(event.data, end="", flush=True)
    elif isinstance(event, WorkflowOutputEvent):
        print(f"Final output: {event.data}")

After:

from agent_framework import AgentResponseUpdate

async for event in workflow.run("Write a blog post about AI agents.", stream=True):
    if event.type == "output" and isinstance(event.data, AgentResponseUpdate):
        print(event.data, end="", flush=True)
    elif event.type == "output":
        print(f"Final output: {event.data}")

형식 주석

Before:

pending_requests: list[RequestInfoEvent] = []
output: WorkflowOutputEvent | None = None

After:

from typing import Any
from agent_framework import WorkflowEvent

pending_requests: list[WorkflowEvent[Any]] = []
output: WorkflowEvent | None = None

비고

WorkflowEvent는 제네릭(WorkflowEvent[DataT])이지만, 혼합 이벤트 컬렉션의 경우 WorkflowEvent[Any] 또는 매개변수가 없는 WorkflowEvent을(를) 사용하십시오.

🔴 `workflow.send_responses*` 제거; 사용 `workflow.run(responses=...)`

PR:#3720

send_responses() 및 send_responses_streaming()이 Workflow에서 제거되었습니다. 응답을 직접 전달하여 일시 중지된 워크플로를 계속합니다 run().

Before:

async for event in workflow.send_responses_streaming(
    checkpoint_id=checkpoint_id,
    responses=[approved_response],
):
    ...

After:

async for event in workflow.run(
    checkpoint_id=checkpoint_id,
    responses=[approved_response],
    stream=True,
):
    ...

🔴 `SharedState` 이름이 `State`로 변경되었습니다. 워크플로 상태 API는 동기식입니다.

PR:#3667

상태 API는 더 이상 await가 필요하지 않으며, 명명 규칙이 표준화되었습니다.

이전	이후
`ctx.shared_state`	`ctx.state`
`await ctx.get_shared_state("k")`	`ctx.get_state("k")`
`await ctx.set_shared_state("k", v)`	`ctx.set_state("k", v)`
`checkpoint.shared_state`	`checkpoint.state`

🔴 오케스트레이션 빌더가 `agent_framework.orchestrations`로 이동했습니다

PR:#3685

오케스트레이션 빌더는 이제 전용 패키지 네임스페이스에 있습니다.

Before:

from agent_framework import SequentialBuilder, GroupChatBuilder

After:

from agent_framework.orchestrations import SequentialBuilder, GroupChatBuilder

🟡 장기 실행 백그라운드 응답 및 연속 토큰들

PR:#3808

이제 options={"background": True} 및 continuation_token를 통해 Python 에이전트 실행에 대한 백그라운드 응답이 지원됩니다.

response = await agent.run("Long task", options={"background": True})
while response.continuation_token is not None:
    response = await agent.run(options={"continuation_token": response.continuation_token})

🟡 나란히 추가된 세션/컨텍스트 공급자 미리 보기 형식

PR:#3763

증분 마이그레이션 SessionContextBaseContextProvider을 위한 레거시 API와 함께 새 세션/컨텍스트 파이프라인 유형이 도입되었습니다.

🟡 이제 코드 인터프리터 스트리밍에 증분 코드 델타가 포함됩니다.

PR:#3775

이제 스트리밍 코드 인터프리터가 실행되어 UI가 생성된 코드를 점진적으로 렌더링할 수 있도록 스트리밍된 콘텐츠에서 코드 델타 업데이트를 표시합니다.

🟡 `@tool` 는 명시적 스키마 처리를 지원합니다.

PR:#3734

이제 유추된 스키마 출력에 사용자 지정이 필요한 경우 도구 정의에서 명시적 스키마 처리를 사용할 수 있습니다.

python-1.0.0b260130(2026년 1월 30일)

릴리스 정보:python-1.0.0b260130

이제 🟡`ChatOptions` 및 `ChatResponse`/`AgentResponse`는 응답 형식에 대해 제네릭으로 처리됩니다.

PR:#3305

ChatOptions, ChatResponse이제 AgentResponse 제네릭 형식이 응답 형식 형식으로 매개 변수화됩니다. 이렇게 하면 구조화된 출력을 사용할 때 형식 유추를 향상할 수 있습니다 response_format.

Before:

from agent_framework import ChatOptions, ChatResponse
from pydantic import BaseModel

class MyOutput(BaseModel):
    name: str
    score: int

options: ChatOptions = {"response_format": MyOutput}  # No type inference
response: ChatResponse = await client.get_response("Query", options=options)
result = response.value  # Type: Any

After:

from agent_framework import ChatOptions, ChatResponse
from pydantic import BaseModel

class MyOutput(BaseModel):
    name: str
    score: int

options: ChatOptions[MyOutput] = {"response_format": MyOutput}  # Generic parameter
response: ChatResponse[MyOutput] = await client.get_response("Query", options=options)
result = response.value  # Type: MyOutput | None (inferred!)

Tip

이는 비파괴적 향상입니다. 형식 매개 변수가 없는 기존 코드는 계속 작동합니다. 옵션 및 응답에 대해 위의 코드 조각에서 형식을 지정할 필요가 없습니다. 명확성을 위해 여기에 표시됩니다.

🟡 `BaseAgent` Claude 에이전트 SDK에 대한 지원이 추가됨

PR:#3509

이제 Python SDK에 Claude 에이전트 SDK의 구현이 포함되어, 에이전트 프레임워크에서 최상위 어댑터 기반 사용을 가능하게 합니다.

python-1.0.0b260128(2026년 1월 28일)

릴리스 정보:python-1.0.0b260128

🔴 `AIFunction`는 `FunctionTool`로 이름이 변경되고, `@ai_function`는 `@tool`로 이름이 변경되었습니다.

PR:#3413

클래스 및 데코레이터는 업계 용어와의 명확성과 일관성을 위해 이름이 바뀌었습니다.

Before:

from agent_framework.core import ai_function, AIFunction

@ai_function
def get_weather(city: str) -> str:
    """Get the weather for a city."""
    return f"Weather in {city}: Sunny"

# Or using the class directly
func = AIFunction(get_weather)

After:

from agent_framework import FunctionTool, tool

@tool
def get_weather(city: str) -> str:
    """Get the weather for a city."""
    return f"Weather in {city}: Sunny"

# Or using the class directly
func = FunctionTool(get_weather)

🔴 GroupChat 및 Magentic에 추가된 팩터리 패턴 API 이름 바꾸기

PR:#3224

그룹 채팅에 참가자 팩터리 및 오케스트레이터 팩터리를 추가했습니다. 이름 바꾸기도 포함됩니다.

with_standard_manager → with_manager
participant_factories → register_participant

Before:

from agent_framework.workflows import MagenticBuilder

builder = MagenticBuilder()
builder.with_standard_manager(manager)
builder.participant_factories(factory1, factory2)

After:

from agent_framework.orchestrations import MagenticBuilder

builder = MagenticBuilder()
builder.with_manager(manager)
builder.register_participant(factory1)
builder.register_participant(factory2)

🔴 `Github` 이름이 `GitHub`로 변경됨

PR:#3486

클래스 및 패키지 이름이 대소문자를 올바르게 사용하도록 업데이트되었습니다.

Before:

from agent_framework_github_copilot import GithubCopilotAgent

agent = GithubCopilotAgent(...)

After:

from agent_framework_github_copilot import GitHubCopilotAgent

agent = GitHubCopilotAgent(...)

python-1.0.0b260127(2026년 1월 27일)

릴리스 정보:python-1.0.0b260127

🟡 `BaseAgent` GitHub Copilot SDK에 대한 지원이 추가됨

PR:#3404

이제 Python SDK에는 GitHub Copilot SDK 통합을 위한 구현이 포함 BaseAgent 됩니다.

python-1.0.0b260123(2026년 1월 23일)

릴리스 정보:python-1.0.0b260123

🔴 classmethod 생성자를 사용하여 단일 클래스로 간소화된 콘텐츠 형식

PR:#3252

특정 형식을 만들기 위해 모든 이전 콘텐츠 형식(파생 BaseContent)을 classmethods가 있는 단일 Content 클래스로 바꿉니다.

전체 마이그레이션 레퍼런스

이전 형식	새 메서드
`TextContent(text=...)`	`Content.from_text(text=...)`
`DataContent(data=..., media_type=...)`	`Content.from_data(data=..., media_type=...)`
`UriContent(uri=..., media_type=...)`	`Content.from_uri(uri=..., media_type=...)`
`ErrorContent(message=...)`	`Content.from_error(message=...)`
`HostedFileContent(file_id=...)`	`Content.from_hosted_file(file_id=...)`
`FunctionCallContent(name=..., arguments=..., call_id=...)`	`Content.from_function_call(name=..., arguments=..., call_id=...)`
`FunctionResultContent(call_id=..., result=...)`	`Content.from_function_result(call_id=..., result=...)`
`FunctionApprovalRequestContent(...)`	`Content.from_function_approval_request(...)`
`FunctionApprovalResponseContent(...)`	`Content.from_function_approval_response(...)`

추가 새 메서드(직접 선행 작업 없음):

Content.from_text_reasoning(...) — 추론/사고 콘텐츠
Content.from_hosted_vector_store(...) — 벡터 저장소 참조의 경우
Content.from_usage(...) — 사용량/토큰 정보
Content.from_mcp_server_tool_call(...) / Content.from_mcp_server_tool_result(...) — MCP 서버 도구용
Content.from_code_interpreter_tool_call(...) / Content.from_code_interpreter_tool_result(...) — 코드 인터프리터의 경우
Content.from_image_generation_tool_call(...) / Content.from_image_generation_tool_result(...) — 이미지 생성용

형식 검사

isinstance() 검사를 대신하여 type 속성을 사용하십시오.

Before:

from agent_framework.core import TextContent, FunctionCallContent

if isinstance(content, TextContent):
    print(content.text)
elif isinstance(content, FunctionCallContent):
    print(content.name)

After:

from agent_framework import Content

if content.type == "text":
    print(content.text)
elif content.type == "function_call":
    print(content.name)

기본 예제

Before:

from agent_framework.core import TextContent, DataContent, UriContent

text = TextContent(text="Hello world")
data = DataContent(data=b"binary", media_type="application/octet-stream")
uri = UriContent(uri="https://example.com/image.png", media_type="image/png")

After:

from agent_framework import Content

text = Content.from_text("Hello world")
data = Content.from_data(data=b"binary", media_type="application/octet-stream")
uri = Content.from_uri(uri="https://example.com/image.png", media_type="image/png")

🔴 주석 유형이 `Annotation` 및 `TextSpanRegion` TypedDicts로 단순화됨

PR:#3252

클래스 기반 주석 형식을 더 TypedDict 간단한 정의로 바꿉니다.

이전 형식	새 형식
`CitationAnnotation` (클래스)	`Annotation` (TypedDict 와 함께 `type="citation"`)
`BaseAnnotation` (클래스)	`Annotation` (TypedDict)
`TextSpanRegion` (`SerializationMixin`이 포함된 클래스)	`TextSpanRegion` (TypedDict)
`Annotations` (형식 별칭)	`Annotation`
`AnnotatedRegions` (형식 별칭)	`TextSpanRegion`

Before:

from agent_framework import CitationAnnotation, TextSpanRegion

region = TextSpanRegion(start_index=0, end_index=25)
citation = CitationAnnotation(
    annotated_regions=[region],
    url="https://example.com/source",
    title="Source Title"
)

After:

from agent_framework import Annotation, TextSpanRegion

region: TextSpanRegion = {"start_index": 0, "end_index": 25}
citation: Annotation = {
    "type": "citation",
    "annotated_regions": [region],
    "url": "https://example.com/source",
    "title": "Source Title"
}

비고

Annotation와 TextSpanRegion가 이제 TypedDict이므로, 이를 클래스 인스턴스가 아닌 사전으로 생성합니다.

🔴 `response_format` 이제 사용자에게 유효성 검사 오류가 표시됩니다.

PR:#3274

ChatResponse.value 및 AgentResponse.value 스키마 유효성 검사가 실패할 때 ValidationError을(를) 발생시키고, 더 이상 None을(를) 조용히 반환하지 않습니다.

Before:

response = await agent.run(query, options={"response_format": MySchema})
if response.value:  # Returns None on validation failure - no error details
    print(response.value.name)

After:

from pydantic import ValidationError

# Option 1: Catch validation errors
try:
    print(response.value.name)  # Raises ValidationError on failure
except ValidationError as e:
    print(f"Validation failed: {e}")

# Option 2: Safe parsing (returns None on failure)
if result := response.try_parse_value(MySchema):
    print(result.name)

🔴 AG-UI 실행 로직 단순화, MCP 및 Anthropic 클라이언트 수정 사항 적용

PR:#3322

runAG-UI 메서드 서명 및 동작이 간소화되었습니다.

Before:

from agent_framework.ag_ui import AGUIEndpoint

endpoint = AGUIEndpoint(agent=agent)
result = await endpoint.run(
    request=request,
    run_config={"streaming": True, "timeout": 30}
)

After:

from agent_framework.ag_ui import AgentFrameworkAgent

agui_agent = AgentFrameworkAgent(agent=agent)
async for event in agui_agent.run(request):
    ...

🟡 이제 Anthropic 클라이언트가 구조화된 출력을 `response_format` 지원합니다.

PR:#3301

이제 OpenAI 및 Azure 클라이언트와 유사하게, response_format를 통해 Anthropic 클라이언트와 구조화된 출력 구문 분석을 사용할 수 있습니다.

🟡 확장된 Azure AI 구성(`reasoning`, `rai_config`)

PR:#3403, #3265

Azure AI 지원은 추론 구성 지원 및 rai_config 에이전트 생성 중에 확장되었습니다.

python-1.0.0b260116(2026년 1월 16일)

릴리스 정보:python-1.0.0b260116

🔴 `create_agent` 이름이 `as_agent`로 변경됨

PR:#3249

메서드의 용도에 대한 명확성을 높이기 위해 이름이 바뀌었습니다.

Before:

from agent_framework.core import ChatClient

client = ChatClient(...)
agent = client.create_agent()

After:

from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient(...)
agent = client.as_agent()

🔴 `WorkflowOutputEvent.source_executor_id` 이름이 `executor_id`로 변경됨

PR:#3166

API 일관성을 위해 이름이 변경된 속성입니다.

Before:

async for event in workflow.run_stream(...):
    if isinstance(event, WorkflowOutputEvent):
        executor = event.source_executor_id

After:

async for event in workflow.run(..., stream=True):
    if event.type == "output":
        executor = event.executor_id

🟡 AG-UI 서비스 관리 세션 연속성을 지원합니다.

PR:#3136

AG-UI는 이제 다중 턴 연속성을 유지하기 위해 서비스 관리 대화 ID(예: Foundry 관리 세션/스레드)를 보존합니다.

python-1.0.0b260114(2026년 1월 14일)

릴리스 정보:python-1.0.0b260114

🔴 리팩터링된 오케스트레이션

PR:#3023

에이전트 프레임워크 워크플로에서 오케스트레이션의 광범위한 리팩터링 및 간소화:

그룹 채팅: 오케스트레이터 실행기를 전용 에이전트 기반 및 함수 기반(BaseGroupChatOrchestrator, GroupChatOrchestrator, AgentBasedGroupChatOrchestrator)으로 분할합니다. 브로드캐스팅 모델을 사용하여 스타 토폴로지로 간소화되었습니다.
핸드오프: 단일 계층, 코디네이터 및 사용자 지정 실행기 지원이 제거되었습니다. HandoffAgentExecutor를 사용하여 방송 모델로 이동했습니다.
순차 및 병렬: AgentApprovalExecutor 및 AgentRequestInfoExecutor를 사용하는 하위 워크플로에 의존하도록 요청 정보 메커니즘을 단순화했습니다.

Before:

from agent_framework.workflows import GroupChat, HandoffOrchestrator

# Group chat with custom coordinator
group = GroupChat(
    participants=[agent1, agent2],
    coordinator=my_coordinator
)

# Handoff with single tier
handoff = HandoffOrchestrator(
    agents=[agent1, agent2],
    tier="single"
)

After:

from agent_framework.orchestrations import (
    GroupChatOrchestrator,
    HandoffAgentExecutor,
)

# Group chat with star topology
group = GroupChatOrchestrator(
    participants=[agent1, agent2]
)

# Handoff with executor-based approach
handoff = HandoffAgentExecutor(
    agents=[agent1, agent2]
)

🔴 TypedDict 및 제네릭으로 도입된 옵션

PR:#3140

옵션은 이제 더 나은 형식 안전성 및 IDE 자동 완성을 위해 TypedDict로 입력됩니다.

📖 전체 마이그레이션 지침은 형식화된 옵션 가이드를 참조하세요.

Before:

response = await client.get_response(
    "Hello!",
    model_id="gpt-4",
    temperature=0.7,
    max_tokens=1000,
)

After:

response = await client.get_response(
    "Hello!",
    options={
        "model": "gpt-4",
        "temperature": 0.7,
        "max_tokens": 1000,
    },
)

🔴 `display_name` 제거; `context_provider` 단수로, `middleware` 목록이어야 합니다.

PR:#3139

display_name 에이전트에서 제거된 매개 변수
context_providers 는 공급자에 대한 현재 복수 시퀀스 매개 변수로 유지됩니다.
middleware 이제 목록이 필요합니다(더 이상 단일 인스턴스를 허용하지 않음).
AggregateContextProvider 코드에서 제거됨(필요한 경우 샘플 구현 사용)

Before:

from agent_framework.core import Agent, AggregateContextProvider

agent = Agent(
    name="my-agent",
    display_name="My Agent",
    context_providers=[provider1, provider2],
    middleware=my_middleware,  # single instance was allowed
)

aggregate = AggregateContextProvider([provider1, provider2])

After:

from agent_framework import Agent

agent = Agent(
    name="my-agent",  # display_name removed
    client=client,
    context_providers=[provider1, provider2],
    middleware=[my_middleware],  # must be a list now
)

# For reusable provider composition, create your own aggregate
class MyAggregateProvider:
    def __init__(self, providers):
        self.providers = providers
    # ... implement aggregation logic

🔴 `AgentRunResponse` 이름이 `AgentResponse`로 변경됨

PR:#3207

AgentRunResponse 및 AgentRunResponseUpdate는 AgentResponse 및 AgentResponseUpdate으로 이름이 바뀌었습니다.

Before:

from agent_framework import AgentRunResponse, AgentRunResponseUpdate

After:

from agent_framework import AgentResponse, AgentResponseUpdate

🟡 YAML 정의 워크플로에 대해 추가된 선언적 워크플로 런타임

PR:#2815

선언적 YAML 워크플로를 실행하기 위해 그래프 기반 런타임이 추가되어 사용자 지정 런타임 코드 없이 다중 에이전트 오케스트레이션을 사용하도록 설정했습니다.

🟡 MCP 성능/안정성 향상

PR:#3154

MCP 통합은 향상된 연결 손실 동작, 로드 시 페이지 매김 지원 및 표현 제어 옵션을 얻었습니다.

🟡 이제 Foundry `A2ATool` 는 대상 URL 없이 연결을 지원합니다.

PR:#3127

A2ATool 이제 직접 대상 URL이 구성되지 않은 경우에도 프로젝트 연결 메타데이터를 통해 Foundry 지원 A2A 연결을 확인할 수 있습니다.

python-1.0.0b260107(2026년 1월 7일)

릴리스 정보:python-1.0.0b260107

이 릴리스에는 큰 변화가 없습니다.

python-1.0.0b260106(2026년 1월 6일)

릴리스 정보:python-1.0.0b260106

이 릴리스에는 큰 변화가 없습니다.

요약 표

Release	릴리스 노트	Type	변경	PR
미공개	—	🔴 속보	미들웨어 입력에는 시퀀스가 필요합니다. 제거된 코어 엑스트라를 사용하는 대신 `agent-hooks-sdk`를 직접 설치하세요.	#7918
1.15.0	Notes	🟡 개선	`MiddlewareFailure`에 함수 미들웨어용 치명적 fail-closed 동작을 추가합니다.	#7562
1.14.0	Notes	🟡 개선	암호화된 추론이 Foundry 채팅에 옵트인됨	#7536
1.14.0	Notes	🟡 개선	에이전트 후크가 실험적 AGENT-HOOKS-0.1 가로채기 미들웨어를 추가합니다.	#7515
1.8.0	Notes	🔴 속보	`github-copilot-sdk` v1.0.0으로 업그레이드됨: `SubprocessConfig` 제거됨(`RuntimeConnection` + kwargs 사용), 가져오기 경로가 `copilot.session_events`로 이동, `copilot_home` → `base_directory`, 권한 핸들러는 구체적인 결정 유형을 사용	#6292
1.8.0	Notes	🟡 개선	`FunctionInvocationContext`를 통한 점진적인 도구 노출	#6233
1.8.0	Notes	🟡 개선	MCP 기반 기술 검색(`McpSkillsSource`)	#6169
1.8.0	Notes	🟡 개선	Converse API를 통한 Bedrock 네이티브 구조화된 출력 지원	#6052
1.8.0	Notes	🟡 개선	Foundry Adaptive Evals 통합(루브릭 생성)	#6101
1.8.0	Notes	🟡 개선	Mistral AI 포함 클라이언트 패키지	#5480
1.8.0	Notes	🟡 개선	`agent-framework-declarative` 릴리스 후보로 승격됨	#6256
1.7.0	Notes	🔴 속보	선언적: Python 전용 작업이 제거되고 별칭 종류 이름이 C# 정식 이름으로 바뀌었습니다.	#6126
1.7.0	Notes	🟡 개선	`HarnessAgent` 및 백그라운드 에이전트 하네스 제공자 추가됨	#6041
1.7.0	Notes	🟡 개선	참조된 작업 ID 및 입력 필요 지원이 포함된 `A2AAgentSession`	#5980
1.6.0	Notes	🔴 속보	코어 및 파운드리 패키지에서 계측 기능이 기본적으로 활성화됨	#5865
1.6.0	Notes	🟡 개선	로컬 및 Docker 실행 지원이 있는 셸 도구	#5664
1.6.0	Notes	🟡 개선	새 `agent-framework-monty` CodeAct 공급자 패키지	#5915
1.4.0	Notes	🔴 속보	[실험적 기술] 파일 기술 폴더 검색을 agentskills.io 사양에 맞게 조정	#5807
1.4.0	Notes	🔴 속보	[실험적 기술] 기술 사양 메타데이터 추출 `SkillFrontmatter`	#5775
1.4.0	Notes	🔴 속보	DevUI: 기본 액세스 제어 및 CORS 상태 강화	#5740
1.4.0	Notes	🔴 속보	A2A: a2a-sdk v1.0으로 마이그레이션	#5752
1.3.0	Notes	🔴 속보	[실험적 기술] 다중 소스 아키텍처에 대한 에이전트 기술 재구성	#5584
1.3.0	Notes	🟡 개선	`ClassSkill` 선언적 메타데이터를 사용하는 클래스 기반 스킬 정의용	#5678
1.3.0	Notes	🟡 개선	정보 흐름 제어 프롬프트 인젝션 방어	#5331
1.3.0	Notes	🟡 개선	`github-copilot-sdk`가 `instruction_directories` 및 `copilot_home`와 함께 v1.0.0b2로 업그레이드됨	#5665
1.2.2	Notes	🔴 속보	오케스트레이션 터미널 출력은 표준화되고 `AgentResponseWorkflow.as_agent()` 최종 답변만 반환됩니다.	#5301
1.2.2	Notes	🟡 개선	AZURE AI Content Understanding 컨텍스트 공급자 패키지	#4829
1.1.0	Notes	🔴 속보	`CosmosCheckpointStorage` 기본적으로 pickle 역직렬화를 제한	#5200
1.1.0	Notes	🟡 개선	`GeminiChatClient` 추가	#4847
1.1.0	Notes	🟡 개선	Hyperlight CodeAct 패키지	#5185
1.1.0	Notes	🟡 개선	Foundry 도구 상자 지원	#5346
1.1.0	Notes	🟡 개선	`AgentResponse` 및 `AgentResponseUpdate`의 `finish_reason`	#5211
1.0.1	Notes	🔴 속보	`FileCheckpointStorage`의 제한된 피클 역직렬화(보안 강화)	#4941
1.0.1	Notes	🔴 속보	핸드오프 워크플로 컨텍스트 관리 수정	#5136
1.0.1	Notes	🟡 개선	워크플로에 대한 Cosmos DB NoSQL 검사점 스토리지	#4916
1.0.0	Notes	🔴 속보	`Message(..., text=...)` 구성이 완전히 제거되었습니다. 이제 `contents=[...]`로 문자 메시지를 만드십시오.	#5062
1.0.0	Notes	🟡 개선	릴리스된 Python 패키지(`agent-framework`, `agent-framework-core`, `agent-framework-openai`, `agent-framework-foundry`)는 `--pre`를 더 이상 필요로 하지 않습니다. 하지만 베타 커넥터는 여전히 필요합니다.	#5062
1.0.0	Notes	🔴 속보	Python 포함은 `agent_framework.foundry`로 이동되었으며, 제거된 `agent-framework-foundry` 패키지 대신 `FoundryEmbeddingClient`, `FOUNDRY_MODELS_*`, `agent-framework-azure-ai` 설정을 사용하십시오.	#5056
1.0.0	Notes	🔴 속보	`workflow.run()` 이제 전역 대상 및 실행기별 대상 지정을 실행기 ID에 의해 결정되는 명시적 `function_invocation_kwargs` / `client_kwargs`을 사용합니다.	#5010
1.0.0	Notes	🟡 개선	`GitHubCopilotAgent` 이제 컨텍스트 공급자 `before_run` / `after_run` 후크를 호출하고 공급자가 추가한 프롬프트 컨텍스트를 포함합니다.	#5013
1.0.0	Notes	🟡 개선	Python 구조화된 출력은 이제 `response_format`로 JSON 스키마 매핑을 허용하며, 구문 분석된 JSON은 `response.value`에 표시됩니다.	#5022
1.0.0rc6	PR 전용	🔴 속보	사용되지 않는 Azure/OpenAI 호환성 화면이 제거되었습니다. 공급자를 선도하는 OpenAI 클라이언트 또는 Foundry Python 클라이언트를 대신 사용	#4990
1.0.0rc6	PR 전용	🔴 속보	공급자 주도의 리팩터링: `agent-framework-openai`, `agent-framework-foundry`, `agent-framework-foundry-local`를 각각 분할하고, OpenAI 클라이언트를 이름 변경합니다. 그리고 Foundry를 `agent_framework.foundry`로 이동하며, Azure AI 및 Assistants 호환 경로를 폐기합니다.	#4818
1.0.0rc6	PR 전용	🔴 속보	`agent-framework-core`는 이제 의도적으로 슬림합니다. `agent-framework-openai` 또는 `agent-framework-foundry`와 같은 명시적 공급자 패키지를 설치하고, 최소 설치 시 MCP 도구용으로 `mcp`를 수동으로 설치하거나, 더 광범위한 기본 환경을 위해 `agent-framework` 메타 패키지를 사용하십시오.	#4904
1.0.0rc6	PR 전용	🔴 속보	이제 일반 `agent_framework.openai` 클라이언트는 명시적 라우팅 신호를 선호합니다. `OPENAI_API_KEY`가 설정된 경우 OpenAI는 OpenAI로 유지되며, Azure 시나리오에서는 `credential` 또는 `azure_endpoint`와 같은 명시적 Azure 라우팅 입력을 전달한 후 `api_version`를 구성해야 합니다.	#4925
1.0.0rc5 / 1.0.0b260318	N/A(예약됨)	🔴 속보	퍼블릭 런타임 kwargs가 `function_invocation_kwargs`와 `client_kwargs`로 나누어졌고, 도구는 이제 `FunctionInvocationContext` / `ctx.session`를 사용합니다.	#4581
1.0.0rc4 / 1.0.0b260311	Notes	🔴 속보	이제 Azure AI 통합은 `azure-ai-projects` 2.0 GA를 목표로 하고 있으며, `foundry_features` 는 제거되었고 `allow_preview` 는 미리 보기 옵트인 옵션입니다.	#4536
1.0.0rc4 / 1.0.0b260311	Notes	🔴 속보	이제 GitHub Copilot 통합이 사용됩니다`ToolInvocation` / `ToolResultagent-framework-github-copilot`. Python 3.11 이상 필요	#4551
1.0.0rc3 / 1.0.0b260304	Notes	🔴 속보	기술 제공자에 코드로 정의된 `Skill` / `SkillResource`가 추가되었으며, 이전 `FileAgentSkillsProvider` 가져오기 및 백틱 리소스 참조를 업데이트해야 합니다	#4387
1.0.0rc2 / 1.0.0b260226	Notes	🔴 속보	선언적 워크플로는 `InvokeTool`을(를) `InvokeFunctionTool` 및 `WorkflowFactory.register_tool()`로 대체합니다.	#3716
1.0.0rc1 / 1.0.0b260219	Notes	🔴 속보	Azure 패키지 간 통합 Azure 자격 증명 처리	#4088
1.0.0rc1 / 1.0.0b260219	Notes	🔴 속보	아래에서 다시 디자인된 Python 예외 계층 구조 `AgentFrameworkException`	#4082
1.0.0rc1 / 1.0.0b260219	Notes	🔴 속보	공급자 상태는 이제 `source_id`에 의해 범위가 지정됩니다.	#3995
1.0.0rc1 / 1.0.0b260219	Notes	🔴 속보	사용자 지정 `get_response()` 구현은 `Sequence[Message]`를 수락해야 합니다.	#3920
1.0.0rc1 / 1.0.0b260219	Notes	🔴 속보	`FunctionTool[Any]` 스키마 passthrough shim이 제거됨	#3907
1.0.0rc1 / 1.0.0b260219	Notes	🔴 속보	설정이 `AFBaseSettings`/pydantic-settings에서 `TypedDict` + `load_settings()`로 이동되었습니다.	#3843, #4032
1.0.0rc1 / 1.0.0b260219	Notes	🟡 개선	추론 모델 워크플로 전환 및 기록 직렬화가 수정됨	#4083
1.0.0rc1 / 1.0.0b260219	Notes	🟡 개선	Bedrock이 `core[all]`에 추가되었습니다. 도구 선택 기본값이 수정되었습니다.	#3953
1.0.0rc1 / 1.0.0b260219	Notes	🟡 개선	`AzureAIClient` 지원되지 않는 런타임 재정의에 대한 경고	#3919
1.0.0rc1 / 1.0.0b260219	Notes	🟡 개선	`workflow.as_agent()` 공급자가 설정되지 않은 경우 로컬 기록을 삽입합니다.	#3918
1.0.0rc1 / 1.0.0b260219	Notes	🟡 개선	OpenTelemetry 추적 컨텍스트가 MCP 요청에 전파됩니다.	#3780
1.0.0rc1 / 1.0.0b260219	Notes	🟡 개선	Azure Functions에 대해 추가된 지속성 워크플로 지원	#3630
1.0.0b260212	Notes	🔴 속보	`HostedTool` 클래스가 제거되었습니다. 클라이언트 `get__tool()` 메서드를 통해 호스트된 도구 만들기	#3634
1.0.0b260212	Notes	🔴 속보	세션/컨텍스트 공급자 파이프라인 완료: `AgentThread` 제거됨, 사용 `AgentSession` + `context_providers`	#3850
1.0.0b260212	Notes	🔴 속보	검사점 모델/스토리지 리팩터링(`workflow_id` 제거, 추가, `previous_checkpoint_id` 스토리지 동작 변경)	#3744
1.0.0b260212	Notes	🟡 개선	`AzureOpenAIResponsesClient`는 Foundry 프로젝트 엔드포인트에서 생성할 수 있으며 `AIProjectClient`	#3814
1.0.0b260212	Notes	🔴 속보	미들웨어 연속에서는 더 이상 `context`를 수락하지 않으므로 `call_next(context)`를 `call_next()`로 업데이트하십시오.	#3829
1.0.0b260210	Notes	🔴 속보	`send_responses()` / `send_responses_streaming()` 제거; 사용 `workflow.run(responses=...)`	#3720
1.0.0b260210	Notes	🔴 속보	`SharedState` `State`→; 워크플로 상태 API가 동기적이며 검사점 상태 필드 이름이 바뀝니다.	#3667
1.0.0b260210	Notes	🔴 속보	오케스트레이션 작성기가 `agent_framework.orchestrations` 패키지로 이동되었습니다.	#3685
1.0.0b260210	Notes	🟡 개선	Python 에이전트 응답에 추가된 백그라운드 응답 및 `continuation_token` 지원	#3808
1.0.0b260210	Notes	🟡 개선	나란히 추가된 세션/컨텍스트 미리 보기 형식(`SessionContext`, `BaseContextProvider`)	#3763
1.0.0b260210	Notes	🟡 개선	이제 스트리밍 코드 인터프리터 업데이트에 증분 코드 델타가 포함됩니다.	#3775
1.0.0b260210	Notes	🟡 개선	`@tool` 데코레이터에서 명시적 스키마 처리 지원을 추가합니다.	#3734
1.0.0b260210	Notes	🔴 속보	`register_executor()` / `register_agent()`가 `WorkflowBuilder`에서 제거됨; 상태 격리를 위해 인스턴스를 직접 사용하거나 도우미 메서드를 사용하십시오.	#3781
1.0.0b260210	Notes	🔴 속보	`ChatAgent` → `Agent`, `ChatMessage` → `Message`, `RawChatAgent` → `RawAgent`, `ChatClientProtocol` → `SupportsChatGetResponse`	#3747
1.0.0b260210	Notes	🔴 속보	형식 API 검토: `Role`/`FinishReason` 형식 변경, 응답/업데이트 생성자 강화, 도우미 이름 바꾸기 `from_updates`및 제거 `try_parse_value`	#3647
1.0.0b260210	Notes	🔴 속보	API를 중심으로 한 `run`/`get_response` 및 `ResponseStream` 통합	#3379
1.0.0b260210	Notes	🔴 속보	`AgentRunContext` 이름이 로 변경됨 `AgentContext`	#3714
1.0.0b260210	Notes	🔴 속보	`AgentProtocol` 이름이 로 변경됨 `SupportsAgentRun`	#3717
1.0.0b260210	Notes	🔴 속보	미들웨어 `next` 매개변수 이름이 `call_next`로 변경되었습니다.	#3735
1.0.0b260210	Notes	🔴 속보	TypeVar 명명 표준화됨(`TName` → `NameT`)	#3770
1.0.0b260210	Notes	🔴 속보	현재 에이전트 응답 흐름에 맞춰 정렬된 워크플로-에이전트 출력/스트림 동작	#3649
1.0.0b260210	Notes	🔴 속보	Fluent 작성기 메서드가 6개 작성기에서 생성자 매개 변수로 이동됨	#3693
1.0.0b260210	Notes	🔴 속보	워크플로 이벤트는 `WorkflowEvent`에 `type` 판별자로 단일화됩니다. `isinstance()` → `event.type == "..."`	#3690
1.0.0b260130	Notes	🟡 개선	`ChatOptions` / `ChatResponse` / `AgentResponse` 공통의 응답 형식	#3305
1.0.0b260130	Notes	🟡 개선	`BaseAgent` Claude 에이전트 SDK 통합에 대한 지원이 추가됨	#3509
1.0.0b260128	Notes	🔴 속보	`AIFunction` → `FunctionTool`, `@ai_function` → `@tool`	#3413
1.0.0b260128	Notes	🔴 속보	GroupChat/Magentic에 대한 팩터리 패턴; `with_standard_manager` → `with_manager`, `participant_factories` → `register_participant`	#3224
1.0.0b260128	Notes	🔴 속보	`Github` → `GitHub`	#3486
1.0.0b260127	Notes	🟡 개선	`BaseAgent` GitHub Copilot SDK 통합에 대한 지원이 추가됨	#3404
1.0.0b260123	Notes	🔴 속보	classmethods를 사용하여 단일 `Content` 클래스에 통합된 콘텐츠 형식	#3252
1.0.0b260123	Notes	🔴 속보	`response_format` 이제 유효성 검사 오류가 발생합니다. `ValidationError`	#3274
1.0.0b260123	Notes	🔴 속보	AG-UI 실행 로직 간소화	#3322
1.0.0b260123	Notes	🟡 개선	Anthropic 클라이언트는 구조화된 출력에 대한 지원을 추가 `response_format` 합니다.	#3301
1.0.0b260123	Notes	🟡 개선	`reasoning` 및 `rai_config` 지원을 통해 Azure AI 구성 확대	#3403, #3265
1.0.0b260116	Notes	🔴 속보	`create_agent` → `as_agent`	#3249
1.0.0b260116	Notes	🔴 속보	`source_executor_id` → `executor_id`	#3166
1.0.0b260116	Notes	🟡 개선	AG-UI 서비스 관리 세션/스레드 연속성을 지원합니다.	#3136
1.0.0b260114	Notes	🔴 속보	리팩터링된 오케스트레이션 (그룹 채팅, 핸드오프, 순차적 및 동시 수행)	#3023
1.0.0b260114	Notes	🔴 속보	제네릭 및 TypedDict 옵션	#3140
1.0.0b260114	Notes	🔴 속보	`display_name` 제거; `context_providerscontext_provider` →(단수) `middleware` 는 목록이어야 합니다.	#3139
1.0.0b260114	Notes	🔴 속보	이름이 로 변경됨	#3207
1.0.0b260114	Notes	🟡 개선	YAML 정의 워크플로에 대해 추가된 선언적 워크플로 런타임	#2815
1.0.0b260114	Notes	🟡 개선	MCP 로드/안정성 향상(연결 손실 처리, 페이지 매김, 표현 컨트롤)	#3154
1.0.0b260114	Notes	🟡 개선	Foundry `A2ATool` 는 명시적 대상 URL 없이 연결을 지원합니다.	#3127
1.0.0b260107	Notes	—	중요한 변경 내용 없음	—
1.0.0b260106	Notes	—	중요한 변경 내용 없음	—

다음 단계

지원 개요

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-09-10

Python 2026 중요 변경 가이드

미공개

🔴 랩은 별도로 설치되고 Foundry는 프로젝트 2.6을 지원합니다.

🔴 GitHub Copilot 작업 영역 파일 후크는 선택 사항입니다

🔴 파일 백업 스토리지는 공유 경로 정규화를 사용합니다.

🔴 SecretString는 더 이상 str를 상속하지 않음

🔴 미들웨어 입력에는 시퀀스가 필요하며 에이전트 후크는 별도로 설치됩니다.

python-1.16.0(2026년 8월 27일)

🟡 프로그래밍 방식의 OpenTelemetry 공급자 구성

python-1.15.0(2026년 8월 21일)

🔴 OpenTelemetry GenAI 의미 체계 규칙 통합

🟡 함수 미들웨어는 다음을 사용하여 중단할 수 있습니다. MiddlewareFailure

python-1.14.0(2026년 8월 14일)

🟡 암호화된 추론이 Foundry 채팅에 옵트인됨

🔴 [베타] Foundry 호스트 에이전트 상태가 Foundry 상태 저장소로 이동

🔴 함수 워크플로 정의를 실행하기 전에 빌드

🟡 에이전트 후크가 장애 조치(fail-closed) 인터셉션 계약을 추가합니다.

python-1.8.0(2026년 6월 4일)

🔴 github-copilot-sdk가 호환성을 깨뜨리는 API 변경 사항과 함께 v1.0.0으로 업그레이드되었습니다

🟡 FunctionInvocationContext을 통한 도구의 점진적 노출

🟡 MCP 기반 기술 검색(McpSkillsSource)

🟡 Converse API를 통한 Bedrock 기본 구조화된 출력 지원

🟡 Foundry Adaptive Evals 통합(루브릭 생성)

🟡 Mistral AI 임베딩 클라이언트 패키지

🟡 agent-framework-declarative가 릴리스 후보로 승격됨

python-1.7.0(2026년 5월 28일)

🔴 선언적: Python 전용 작업이 제거되고 별칭 종류 이름이 C# 정식 이름으로 바뀌었습니다.

🟡 HarnessAgent 및 백그라운드 에이전트는 공급자를 활용합니다

🟡 참조된 작업 ID 및 입력 필요 지원이 포함된 A2AAgentSession

🟡 실험적 프롬프트 에이전트 변환 및 배포 API

python-1.6.0(2026년 5월 21일)

🔴 기본적으로 활성화된 계측 기능

🟡 로컬 및 Docker 실행 지원이 있는 셸 도구

🟡 새 agent-framework-monty CodeAct 공급자 패키지

python-1.4.0(2026년 5월 14일)

🔴 [실험적 기술 API] 파일 기술 폴더 검색을 agentskills.io 사양에 맞게 조정

🔴 [실험적 기술 API] 기술 사양 메타데이터 추출 SkillFrontmatter

🔴 DevUI: 기본 접근 제어 및 CORS 보안 태세 강화

🔴 A2A: a2a-sdk v1.0으로 마이그레이션

🟡 AG-UI: 도구 결과 표시 채널 및 릴리스 후보로 승격

python-1.3.0(2026년 5월 7일)

🔴 [실험적 기술 API] 다중 소스 아키텍처에 대한 에이전트 기술 재구성

🟡 ClassSkill 클래스 기반 스킬 정의용

🟡 정보 흐름 제어 프롬프트 삽입 방어

🟡 github-copilot-sdk v1.0.0b2로 업그레이드됨

🟡 Claude 및 GitHub Copilot 에이전트에서 approval_mode 적용

🟡 OpenAI 및 Gemini allowed_tools 도구 선택 지원

python-1.2.2(2026년 4월 29일)

🔴 오케스트레이션 터미널 출력은 다음과 같이 표준화됩니다. AgentResponse

🟡 Azure AI Content Understanding 컨텍스트 공급자

🟡 파운드리 호스팅을 통한 호스트된 지속성 워크플로 지원

python-1.1.0(2026년 4월 21일)

🔴 CosmosCheckpointStorage 기본적으로 피클 역직렬화가 제한됨

🟡 GeminiChatClient 추가

🟡 Hyperlight CodeAct 패키지

🟡 Foundry 도구 상자 지원

🟡 AgentResponse 및 AgentResponseUpdate의 finish_reason

🟡 Foundry에서 호스트된 에이전트 V2 지원

python-1.0.1(2026년 4월 9일)

🔴 FileCheckpointStorage의 제한된 피클 역직렬화(보안 강화)

🔴 핸드오프 워크플로 컨텍스트 관리 수정

🟡 워크플로용 Cosmos DB NoSQL 체크포인트 저장소

python-1.0.0(2026년 4월 2일)

🔴 Message(..., text=...) 구조가 이제 완전히 제거되었습니다.

🟡 릴리스된 Python 패키지는 더 이상 필요하지 않습니다. --pre

🔴 이제 Foundry는 Python 포함 및 모델 엔드포인트 설정을 소유합니다.

🔴 워크플로는 이제 명시적 버킷을 통해 런타임 kwargs를 라우팅합니다.

🟡 GitHubCopilotAgent 이제 각 호출을 중심으로 컨텍스트 공급자를 실행합니다.

🟡 이제 구조적 출력은 Pydantic 모델 외에도 JSON 스키마 매핑을 허용합니다.

python-1.0.0rc6

🔴 모델 선택은 다음에서 표준화됩니다. model

🔴 컨텍스트 공급자는 모델 호출당 미들웨어를 추가하고 기록을 유지할 수 있습니다.

🔴 사용 중단된 Azure/OpenAI 호환성 인터페이스가 제거됨

🔴 공급자를 선도하는 클라이언트 디자인 및 패키지 분할

패키지 매핑

🔴 이제 핵심 종속성이 의도적으로 슬림해졌습니다.

🔴 일반 OpenAI 클라이언트는 이제 명시적 라우팅 신호를 선호합니다.

python-1.0.0rc5 / python-1.0.0b260319(2026년 3월 19일)

🔴 채팅 클라이언트 파이프라인 순서 변경: FunctionInvocation이 이제 ChatMiddleware를 래핑합니다.

🔴 공개 런타임 kwargs가 명시적 버킷으로 분할됨

🔴 `SecretString`는 더 이상 `str`를 상속하지 않음

🟡 함수 미들웨어는 다음을 사용하여 중단할 수 있습니다. `MiddlewareFailure`

🔴 `github-copilot-sdk`가 호환성을 깨뜨리는 API 변경 사항과 함께 v1.0.0으로 업그레이드되었습니다

🟡 `FunctionInvocationContext`을 통한 도구의 점진적 노출

🟡 MCP 기반 기술 검색(`McpSkillsSource`)

🟡 `agent-framework-declarative`가 릴리스 후보로 승격됨

🟡 `HarnessAgent` 및 백그라운드 에이전트는 공급자를 활용합니다

🟡 참조된 작업 ID 및 입력 필요 지원이 포함된 `A2AAgentSession`

🟡 새 `agent-framework-monty` CodeAct 공급자 패키지

🔴 [실험적 기술 API] 기술 사양 메타데이터 추출 `SkillFrontmatter`

🟡 `ClassSkill` 클래스 기반 스킬 정의용

🟡 `github-copilot-sdk` v1.0.0b2로 업그레이드됨

🟡 Claude 및 GitHub Copilot 에이전트에서 `approval_mode` 적용

🟡 OpenAI 및 Gemini `allowed_tools` 도구 선택 지원

🔴 오케스트레이션 터미널 출력은 다음과 같이 표준화됩니다. `AgentResponse`

🔴 `CosmosCheckpointStorage` 기본적으로 피클 역직렬화가 제한됨

🟡 `GeminiChatClient` 추가

🟡 `AgentResponse` 및 `AgentResponseUpdate`의 `finish_reason`

🔴 `FileCheckpointStorage`의 제한된 피클 역직렬화(보안 강화)

🔴 `Message(..., text=...)` 구조가 이제 완전히 제거되었습니다.

🟡 릴리스된 Python 패키지는 더 이상 필요하지 않습니다. `--pre`

🟡 `GitHubCopilotAgent` 이제 각 호출을 중심으로 컨텍스트 공급자를 실행합니다.

🔴 모델 선택은 다음에서 표준화됩니다. `model`

🔴 Azure AI 통합은 이제 2.0 GA를 대상으로 `azure-ai-projects` 합니다.

🔴 GitHub Copilot 도구 처리기는 이제 `ToolInvocation` / `ToolResult` 및 Python 3.11 이상을 사용합니다.

🔴 코드 정의에 따라 기술 공급자가 최종 결정됨 `Skill` / `SkillResource`

🔴 선언적 워크플로가 `InvokeTool`을 `InvokeFunctionTool`로 대체합니다.

🔴 공급자 상태를 범위로 지정 `source_id`

🔴 채팅/에이전트 메시지 입력 맞춤(`run` vs `get_response`)

🔴 `FunctionTool[Any]` 스키마 통과를 위해 제네릭 설정이 제거됨

🔴 Pydantic 설정으로 대체됨 `TypedDict` + `load_settings()`

🟡 Bedrock이 `core[all]`에 추가되었고 도구 선택 기본값이 수정됨

🟡 `workflow.as_agent()` 이제 공급자가 설정되지 않은 경우 로컬 기록이 기본값으로 설정됩니다.

🔴 `HostedTool` 클래스가 클라이언트 `get__tool()` 메서드로 대체됨

🔴 세션/컨텍스트 공급자 파이프라인 완료됨(`AgentSession`, `context_providers`)

처음에 `AzureOpenAIResponsesClient`를 통해 나타난 🟡 Foundry 프로젝트의 엔드포인트

🔴 미들웨어 `call_next` 가 더 이상 수락하지 않음 `context`

🔴 워크플로 팩터리 메서드가 제거됨 `WorkflowBuilder`

실행기를 포함한 `WorkflowBuilder`

`WorkflowBuilder` 에이전트가 있는 경우

`try_parse_value`에서 `try/except`를 `.value`로 교체하십시오.

🔴 `run` / `get_response` 통합 모델 및 `ResponseStream` 사용

🔴 미들웨어 연속 매개 변수 이름이 `call_next`로 변경됨 `call_next`

🔴 표준화된 TypeVar 이름(`TName` → `NameT`)

`WorkflowBuilder`

`SequentialBuilder` / `ConcurrentBuilder`

`GroupChatBuilder`

`MagenticBuilder`

`HandoffBuilder`

🔴 워크플로 이벤트가 `WorkflowEvent` 판별자를 사용하여 단일 `type`로 통합됨

`AgentResponseUpdate`를 사용하여 스트리밍

🔴 `workflow.send_responses*` 제거; 사용 `workflow.run(responses=...)`

🔴 `SharedState` 이름이 `State`로 변경되었습니다. 워크플로 상태 API는 동기식입니다.

🔴 오케스트레이션 빌더가 `agent_framework.orchestrations`로 이동했습니다

🟡 `@tool` 는 명시적 스키마 처리를 지원합니다.

이제 🟡`ChatOptions` 및 `ChatResponse`/`AgentResponse`는 응답 형식에 대해 제네릭으로 처리됩니다.

🟡 `BaseAgent` Claude 에이전트 SDK에 대한 지원이 추가됨

🔴 `AIFunction`는 `FunctionTool`로 이름이 변경되고, `@ai_function`는 `@tool`로 이름이 변경되었습니다.