Python: Remove as_agent() from chat clients in vNext #8967

Maintainer-owned vNext task. Community contributors: please do not pick up or start implementing this issue. Removing a public API is a breaking change for the Agent Framework core team to design and schedule.

Summary

Remove as_agent() from chat clients in vNext: BaseChatClient.as_agent() and its RawFoundryAgentChatClient.as_agent() override. Agent(client=client, ...) already creates an agent from any chat client, and the repository's sample guidance already requires it: "Do not use client.as_agent(...) in samples; construct agents explicitly with Agent(client=client, ...)" (samples/AGENTS.md). The shorthand is a second construction path that must mirror the Agent constructor, has drifted from it, and does not behave the same on every client.

Workflow.as_agent() and FunctionalWorkflow.as_agent() are covered by #8949. The findings below come from a design review and were reproduced against main at a91fe66.

Problems

1. It duplicates the Agent constructor, and the copies drift. as_agent() re-declares every Agent parameter and forwards them, so each constructor change must be made twice, with two docstrings. The copies have already diverged in released versions: as_agent() kept accepting function_invocation_configuration after Agent dropped it, failing with TypeError at call time (Python: [Bug]: The as_agent method of BaseChatClient accepts a function_invocation_configuration parameter, but Agent no longer agrees with that. #4985), and its typing rejected MCPStdioTool while Agent accepted it (Python: [Bug]: as_agent tools typing rejects MCPStdioTool #3936). They still differ today:

   • instructions is positional on Agent(client, instructions) but keyword-only on as_agent().
   • default_options, context_providers, and additional_properties are annotated differently, for example OptionsCoT | Mapping[str, Any] on as_agent() versus OptionsCoT on Agent.

2. It means something different on Foundry agent clients. On other clients it returns Agent(client=self, ...). RawFoundryAgentChatClient overrides it to return a FoundryAgent that builds a new client from the project client, agent name, and version, so the agent does not use the client it was called on, and that client's configuration is silently lost:

   returned type: FoundryAgent | agent.client is client: False
   instruction_role:      'developer'               -> None
   compaction_strategy:   SlidingWindowStrategy     -> None
   tokenizer:             CharacterEstimatorTokenizer -> None
   additional_properties: {'team': 'support'}       -> {}
   default_headers:       {'x-tenant': 'contoso'}   -> None
   OpenAI client timeout: 30 -> Timeout(connect=5.0, read=600, write=600, pool=600)
   

   Agent(client=client) keeps the same client. The override also adds a function_invocation_configuration parameter that the base method does not have, so the same as_agent(...) call is not valid on every client.

3. It is not part of the chat client contract. Agent accepts any SupportsChatGetResponse, but that protocol has only additional_properties and get_response(). A client written to the protocol, like the protocol's own docstring example, has no as_agent(), so code written against the protocol cannot rely on it.

4. It reverses the dependency between layers. _agents.py imports _clients.py at module level (L27), so BaseChatClient has to import Agent inside the method (L644) to construct it.

Scope

• Remove BaseChatClient.as_agent() and the RawFoundryAgentChatClient.as_agent() override, with their tests.
• Replace the remaining client.as_agent(...) usage with Agent(client=client, ...), or FoundryAgent(...) for Foundry agents:
  • docstring examples in core (_clients.py), a2a, anthropic, declarative (WorkflowFactory), foundry_local, and orchestrations (handoff);
  • the lab/gaia samples;
  • READMEs and guidance: packages/core/AGENTS.md ("Using as_agent() Shorthand"), packages/hosting, packages/azure-cosmos-memory, samples/05-end-to-end/evaluation/red_teaming, and the 02-agents/chat_client and 02-agents/providers/custom READMEs, which still describe custom_chat_client.py as using as_agent() although it now uses Agent(...).
• Workflow.as_agent() and FunctionalWorkflow.as_agent() are covered by Python: Remove WorkflowAgent and Workflow.as_agent() in vNext #8949.

Alternative

Use the Agent constructor, which accepts every chat client and keeps using the client instance you pass:

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

For Foundry agents, construct FoundryAgent directly. Samples already follow this pattern, so there will be one documented way to create an agent.

Related

#8949, #8950, #4985, #3936