Skip to content

3. Create an Agent with the SDK

We will create an agent using Python and the Claude SDK (the anthropic package). We use uv for the Python runtime environment throughout.

  1. Install uv.

    Run the following in PowerShell.

    Terminal window
    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  2. Reopen your terminal (or PowerShell), then verify the installation.

    Terminal window
    uv --version

    You should see a version such as uv 0.11.6.

  1. Create a project and move into its folder.

    Terminal window
    uv init quiz-agent
    cd quiz-agent
  2. Install the Claude SDK.

    Terminal window
    uv add anthropic

The environment and agent are “create once, reuse” resources, so we put their creation in a setup script. The contents match what you built from the UI in 1. Create an Agent in the Console, with “-sdk” appended to the names. Since the MCP server is authless, there is no credential vault to create.

  1. In the project folder, create setup.py with the following contents.

    setup.py
    import json
    from anthropic import Anthropic
    client = Anthropic()
    ###############################
    # 1. Create an environment (allow network access to MCP servers)
    ###############################
    environment = client.beta.environments.create(
    name="Quiz-environment-sdk",
    config={
    "type": "cloud",
    "networking": {"type": "limited", "allow_mcp_servers": True},
    },
    )
    print(f"environment: {environment.id}")
    ###############################
    # 2. Create an agent
    ###############################
    SYSTEM_PROMPT = """You are a study assistant that creates AZ-900 (Azure Fundamentals) practice questions using the Microsoft Learn MCP server. Refer to the latest official Microsoft Learn documentation and ask multiple-choice questions one at a time.
    Rules:
    - After presenting the question and the options, do not reveal the correct answer until the user responds.
    - After the user answers, say whether they were right and give a one-line explanation of why each option is correct or incorrect.
    - Provide three real Microsoft Learn documentation URLs that are useful for further study.
    - Remember the user's previous answers (correct/incorrect, topic) within the conversation and prioritize topics they got wrong or are weak in for the next question.
    - Ask only one question at a time and keep a brisk pace."""
    agent = client.beta.agents.create(
    name="AZ-900 Quiz Agent SDK",
    model={"id": "claude-haiku-4-5", "speed": "standard"},
    description="A study assistant that asks AZ-900 (Azure Fundamentals) practice questions using up-to-date information from the Microsoft Learn MCP server.",
    system=SYSTEM_PROMPT,
    mcp_servers=[
    {
    "name": "microsoft-learn",
    "type": "url",
    "url": "https://learn.microsoft.com/api/mcp",
    }
    ],
    tools=[
    {
    "type": "mcp_toolset",
    "mcp_server_name": "microsoft-learn",
    "default_config": {
    "enabled": True,
    "permission_policy": {"type": "always_allow"},
    },
    }
    ],
    )
    print(f"agent: {agent.id}")
    ###############################
    # Save the IDs to a file (used by run.py / chat.py)
    ###############################
    with open("ids.json", "w") as f:
    json.dump(
    {
    "environment_id": environment.id,
    "agent_id": agent.id,
    },
    f,
    indent=2,
    )
    print("Saved the IDs to ids.json")
  2. Run the script.

    Terminal window
    uv run setup.py

    The IDs of the created resources are printed, like this:

    environment: env_018fgtuvYobdrA98ty299UpD
    agent: agent_018ZmPdCappkAQ5g3nc444To
    Saved the IDs to ids.json

Creating a session and talking to the agent go in a script you run each time.

  1. In the project folder, create run.py with the following contents.

    run.py
    import json
    from anthropic import Anthropic
    client = Anthropic()
    ###############################
    # Load the IDs saved by setup.py
    ###############################
    with open("ids.json") as f:
    ids = json.load(f)
    ###############################
    # 1. Create a session (combine the agent and environment; no vault needed)
    ###############################
    session = client.beta.sessions.create(
    agent=ids["agent_id"],
    environment_id=ids["environment_id"],
    )
    print(f"session: {session.id}")
    ###############################
    # 2. Open the event stream first (so no events are missed)
    ###############################
    stream = client.beta.sessions.events.stream(session_id=session.id)
    ###############################
    # 3. Send a message
    ###############################
    client.beta.sessions.events.send(
    session.id,
    events=[
    {
    "type": "user.message",
    "content": [{"type": "text", "text": "Give me one AZ-900 practice question"}],
    }
    ],
    )
    print("Message sent. Waiting for a response...\n")
    ###############################
    # 4. Print events as they arrive
    ###############################
    for event in stream:
    if event.type == "agent.mcp_tool_use":
    print(f"[tool call: {event.name}]")
    elif event.type == "agent.message":
    for block in event.content:
    if block.type == "text":
    print(block.text)
    elif event.type == "session.status_idle":
    if event.stop_reason.type != "requires_action":
    break
    elif event.type == "session.status_terminated":
    break
    stream.close()
    print("\nDone")
  2. Run the script.

    Terminal window
    uv run run.py

    After the tool call, the question is printed in real time.

    session: sesn_01CCczZDALAHspEXUqx9rhFQ
    Message sent. Waiting for a response...
    [tool call: microsoft_docs_search]
    Here is an AZ-900 practice question (topic: cloud concepts - shared responsibility model)
    Question
    A company is planning to migrate an on-premises business application to Azure. ...
    A. ...
    B. ...
    C. ...
    D. ...
    Choose one answer from A to D.
    Done
  3. Running run.py again starts a new session with the same agent. You can also review the resources and session exchanges from the console menus.

run.py ends after a single exchange, so it stops right after the question is asked. Sessions are stateful, so keep sending messages to the same session and the conversation continues. Let’s build an interactive version that goes question → answer → verdict → next question.

  1. In the project folder, create chat.py with the following contents.

    chat.py
    import json
    from anthropic import Anthropic
    client = Anthropic()
    ###############################
    # Load the IDs saved by setup.py
    ###############################
    with open("ids.json") as f:
    ids = json.load(f)
    ###############################
    # Create just one session at the start (keep sending to it and the conversation continues)
    ###############################
    session = client.beta.sessions.create(
    agent=ids["agent_id"],
    environment_id=ids["environment_id"],
    )
    print(f"session: {session.id}")
    print("Chat with the agent. Type exit to quit.\n")
    while True:
    user_input = input("you> ").strip()
    if user_input == "exit":
    break
    if not user_input:
    continue
    ###############################
    # Open the stream, then send the message
    ###############################
    stream = client.beta.sessions.events.stream(session_id=session.id)
    client.beta.sessions.events.send(
    session.id,
    events=[
    {
    "type": "user.message",
    "content": [{"type": "text", "text": user_input}],
    }
    ],
    )
    ###############################
    # Print events until the agent is waiting for input
    ###############################
    for event in stream:
    if event.type == "agent.mcp_tool_use":
    print(f"[tool call: {event.name}]")
    elif event.type == "agent.message":
    for block in event.content:
    if block.type == "text":
    print(block.text)
    elif event.type == "session.status_idle":
    if event.stop_reason.type != "requires_action":
    break
    elif event.type == "session.status_terminated":
    break
    stream.close()
    print()
  2. Run the script and answer the question. After the verdict, send “next” to get the next question.

    Terminal window
    uv run chat.py
    session: sesn_01UDB8UgiKxoFr1myDyGfjf2
    Chat with the agent. Type exit to quit.
    you> Give me one AZ-900 practice question
    [tool call: microsoft_docs_search]
    Here is an AZ-900 practice question (topic: cloud concepts - shared responsibility model)
    ...
    Choose one answer from A to D.
    you> C
    Correct! The answer is C.
    ...
    Score so far: 1 of 1 correct
    you> next
    [tool call: microsoft_docs_search]
    Question 2 ...
    you> exit
  • You built the same setup as the console and CLI with the Python SDK. With an authless MCP server, there is no vault to create or attach to the session.
  • The basic pattern is to separate resource creation (setup.py) from execution (run.py) and pass IDs through ids.json.
  • Open the stream before sending events, and stop receiving at session.status_idle.
  • Sessions are stateful, so simply keep sending to the same session and the “question → answer → verdict” conversation continues (chat.py). No history management is needed on the client.

Great work! Please share your thoughts so far in a post on X.

Share your thoughts on X