AI 原生开放教材

外观

Microsoft Agent Skills技能与配置库·英文原文 ↗仓库 ↗

Agent Framework Azure AI Python Acceptance Criteria ​

SDK: agent-framework-azure-aiRepository: https://github.com/microsoft/agent-frameworkCommit: mainPurpose: Skill testing acceptance criteria for validating generated code correctness

1. Correct Import Patterns ​

1.1 Provider & Credential Imports ​

✅ CORRECT: Provider and async credentials ​

python
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential, DefaultAzureCredential

1.2 Hosted Tools Imports ​

✅ CORRECT: Hosted tool classes ​

python
from agent_framework import (
    HostedCodeInterpreterTool,
    HostedFileSearchTool,
    HostedWebSearchTool,
    HostedFileContent,
    HostedVectorStoreContent,
)

1.3 MCP Tool Imports ​

✅ CORRECT: MCP tool classes ​

python
from agent_framework import HostedMCPTool, MCPStreamableHTTPTool

1.4 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Importing from wrong modules ​

python
# WRONG - Hosted tools are in agent_framework, not agent_framework.azure
from agent_framework.azure import HostedCodeInterpreterTool

# WRONG - Provider is not in agent_framework directly
from agent_framework import AzureAIAgentsProvider

# WRONG - sync credential for async usage
from azure.identity import DefaultAzureCredential

2. AzureAIAgentsProvider Patterns ​

2.1 ✅ CORRECT: Async context manager usage ​

python
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential

async with (
    AzureCliCredential() as credential,
    AzureAIAgentsProvider(credential=credential) as provider,
):
    agent = await provider.create_agent(
        name="MyAgent",
        instructions="You are a helpful assistant.",
    )

2.2 ✅ CORRECT: Provider with explicit configuration ​

python
provider = AzureAIAgentsProvider(
    credential=credential,
    project_endpoint="https://example.services.ai.azure.com/api/projects/my-project",
    model_deployment_name="gpt-4o-mini",
)

2.3 ✅ CORRECT: Provider with existing AgentsClient ​

python
from azure.ai.agents.aio import AgentsClient
from agent_framework.azure import AzureAIAgentsProvider

agents_client = AgentsClient(endpoint=endpoint, credential=credential)
provider = AzureAIAgentsProvider(agents_client=agents_client)

2.4 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Not using context manager ​

python
provider = AzureAIAgentsProvider(credential=credential)
agent = await provider.create_agent(...)  # Missing async context manager

❌ INCORRECT: Mixing sync credential with async provider ​

python
from azure.identity import DefaultAzureCredential

async with AzureAIAgentsProvider(credential=DefaultAzureCredential()) as provider:
    ...

3. Persistent Agents & Threads ​

3.1 ✅ CORRECT: Multi-turn conversation with a thread ​

python
thread = agent.get_new_thread()

result1 = await agent.run("My name is Alice", thread=thread)
result2 = await agent.run("What is my name?", thread=thread)
print(thread.conversation_id)

3.2 ✅ CORRECT: Retrieve existing agent by ID ​

python
agent = await provider.get_agent(agent_id=agent_id)

3.3 ✅ CORRECT: Resume with existing service thread ID ​

python
from agent_framework import AgentThread

thread = AgentThread(service_thread_id=service_thread_id)
result = await agent.run("Continue our conversation", thread=thread)

3.4 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Creating a new thread per message ​

python
for message in messages:
    thread = agent.get_new_thread()  # Loses context
    await agent.run(message, thread=thread)

❌ INCORRECT: Omitting thread for multi-turn conversations ​

python
await agent.run("Message 1")
await agent.run("Message 2")  # No thread; context not preserved

4. Hosted Tools ​

4.1 ✅ CORRECT: HostedCodeInterpreterTool ​

python
from agent_framework import HostedCodeInterpreterTool, HostedFileContent

code_tool = HostedCodeInterpreterTool(
    inputs=[HostedFileContent(file_id="file-abc123")],
)

agent = await provider.create_agent(
    name="DataAnalyst",
    instructions="Analyze the provided file.",
    tools=code_tool,
)

4.2 ✅ CORRECT: HostedFileSearchTool with vector store ​

python
from agent_framework import HostedFileSearchTool, HostedVectorStoreContent

file_search_tool = HostedFileSearchTool(
    inputs=[HostedVectorStoreContent(vector_store_id=vector_store.id)],
    max_results=10,
)

agent = await provider.create_agent(
    name="ResearchAgent",
    instructions="Search uploaded documents.",
    tools=file_search_tool,
)

4.3 ✅ CORRECT: HostedWebSearchTool (Bing) ​

python
from agent_framework import HostedWebSearchTool

agent = await provider.create_agent(
    name="SearchAgent",
    instructions="Use web search for current info.",
    tools=HostedWebSearchTool(
        name="Bing Grounding Search",
        description="Search the web for current information",
    ),
)

4.4 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Passing tool names as strings ​

python
agent = await provider.create_agent(
    name="BadAgent",
    instructions="...",
    tools=["code_interpreter"],
)

❌ INCORRECT: File search without vector store inputs ​

python
file_search_tool = HostedFileSearchTool(inputs=[])
agent = await provider.create_agent(tools=file_search_tool)

5. MCP Server Integration ​

5.1 ✅ CORRECT: HostedMCPTool (service-managed) ​

python
from agent_framework import HostedMCPTool

agent = await provider.create_agent(
    name="DocsAgent",
    instructions="Use Microsoft Learn MCP.",
    tools=HostedMCPTool(
        name="Microsoft Learn MCP",
        url="https://learn.microsoft.com/api/mcp",
        approval_mode="never_require",
        allowed_tools=["microsoft_docs_search", "microsoft_docs_read"],
    ),
)

5.2 ✅ CORRECT: MCPStreamableHTTPTool (client-managed) ​

python
from agent_framework import MCPStreamableHTTPTool

async with MCPStreamableHTTPTool(
    name="Docs MCP",
    url="https://learn.microsoft.com/api/mcp",
) as mcp_tool:
    agent = await provider.create_agent(
        name="DocsAgent",
        instructions="Answer questions using docs.",
        tools=mcp_tool,
    )

5.3 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Missing context manager for MCPStreamableHTTPTool ​

python
mcp_tool = MCPStreamableHTTPTool(name="Docs MCP", url="https://learn.microsoft.com/api/mcp")
agent = await provider.create_agent(tools=mcp_tool)  # Missing async context manager

6. Streaming Patterns ​

6.1 ✅ CORRECT: Stream responses with async iterator ​

python
print("Agent:", end=" ")
async for chunk in agent.run_stream("Tell me a story"):
    if chunk.text:
        print(chunk.text, end="", flush=True)

6.2 ✅ CORRECT: Streaming with threads ​

python
thread = agent.get_new_thread()
async for chunk in agent.run_stream("Continue", thread=thread):
    if chunk.text:
        print(chunk.text, end="", flush=True)

6.3 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Using sync iteration for streaming ​

python
for chunk in agent.run_stream("Hello"):
    print(chunk.text)

❌ INCORRECT: Deprecated stream flag ​

python
response = await agent.run("Hello", stream=True)