ai-agents-for-beginners

Menyebarkan Ejen Skala dengan Microsoft Foundry

Menyebarkan Ejen Skala

Sehingga titik ini dalam kursus, anda telah membina ejen yang berjalan pada komputer riba anda, di dalam buku nota, dipacu oleh az login dan sebilangan pemboleh ubah persekitaran. Itu adalah cara yang tepat untuk belajar. Ia bukan cara yang tepat untuk menjalankan ejen yang bergantung pada ribuan pelanggan pada pukul 3 pagi.

Pelajaran ini mengenai jurang antara “ia berfungsi pada mesin saya” dan “ia berfungsi, dengan boleh dipercayai dan mampu milik, dalam pengeluaran.” Kita menutup jurang itu menggunakan Microsoft Foundry dan Microsoft Foundry Agent Service, dan kita melakukannya dengan membina ejen sokongan pelanggan sebenar yang mempunyai alat, pengambilan, memori, penilaian, dan pemantauan.

Pengenalan

Pelajaran ini akan meliputi:

Matlamat Pembelajaran

Setelah menyelesaikan pelajaran ini, anda akan tahu cara untuk:

Prasyarat

Pelajaran ini mengandaikan anda telah menyelesaikan pelajaran sebelumnya dan selesa dengan:

Anda juga memerlukan:

Dari Prototaip ke Pengeluaran: Apa yang Sebenarnya Berubah

Ejen prototaip dan ejen pengeluaran berkongsi gelung teras yang sama — beralasan, panggil alat, balas. Apa yang berubah adalah segala sesuatu yang membalut gelung itu. Model mungkin hanya 20% dari ejen pengeluaran; 80% yang lain adalah rangka operasi.

Perhatian Prototaip Pengeluaran
Penghosan Berjalan dalam buku nota anda Berjalan sebagai perkhidmatan dihoskan, versi dan dilancar
Identiti Token az login anda Identiti terurus dengan RBAC tertumpu
Keadaan Dalam ingatan, hilang pada muat semula Dielakkan ke luar (penyimpanan utas, perkhidmatan memori)
Kegagalan Anda melihat jejak balik Cuba semula, fallback, dead-letter, amaran
Kos “Ia beberapa sen” Dikesan setiap permintaan, ditempatkan, disimpan dalam cache, dibajetkan
Kualiti Anda menilai output secara visual Dinilai secara automatik sebelum setiap pelepasan
Kepercayaan Anda meluluskan setiap tindakan Polisi + manusia-dalam-gelung untuk tindakan berisiko

Ingat jadual ini. Setiap bahagian berikut memetakan kepada salah satu baris ini.

Corak Penyebaran Ejen

Terdapat tiga corak yang akan anda gunakan, selalunya secara gabungan.

1. Ejen Di Hoskan oleh Klien

Objek ejen wujud dalam proses aplikasi anda. Kod anda memanggil pembekal model secara langsung; gelung beralasan berjalan dalam perkhidmatan anda. Ini adalah apa yang setiap pelajaran sebelum ini telah lakukan.

2. Ejen Di Hoskan (Foundry Agent Service)

Ejen didaftarkan sebagai sumber dalam Microsoft Foundry. Foundry menghoskan gelung beralasan, menyimpan utas, menguatkuasakan keselamatan kandungan dan RBAC, serta menjadikan ejen kelihatan dalam portal Foundry. Aplikasi anda menjadi klien ringan yang mencipta utas dan membaca respons.

3. Aliran Kerja Ejen

Beberapa ejen (dan alat) digabungkan ke dalam graf dengan aliran kawalan eksplisit — langkah berurutan, bercabang, nod kelulusan manusia, dan titik cek tahan lama yang boleh berhenti dan disambung semula. Ini adalah keupayaan Workflows dalam Microsoft Agent Framework yang diterapkan pada skala penyebaran.

flowchart TB
    subgraph P1[Client-Hosted]
        A1[Your App Process] --> M1[Model Provider]
    end
    subgraph P2[Hosted Agent]
        A2[Thin Client] --> F2[Foundry Agent Service]
        F2 --> M2[Model + Tools + Thread Store]
    end
    subgraph P3[Agent Workflow]
        A3[Orchestrator] --> S1[Triage Agent]
        S1 --> S2[Resolver Agent]
        S2 --> H[Human Approval Node]
        H --> S3[Action Agent]
    end

Kitaran Hayat Ejen di Microsoft Foundry

Menyebarkan ejen bukan satu push satu kali. Ia sebuah gelung, dan ia kelihatan banyak seperti kitaran pelepasan perisian kerana itulah sebenarnya ia.

flowchart LR
    Create[Create / Author] --> Version[Version]
    Version --> Evaluate[Evaluate offline]
    Evaluate -->|passes gate| Deploy[Deploy hosted]
    Evaluate -->|fails gate| Create
    Deploy --> Observe[Observe online]
    Observe --> Improve[Collect failures]
    Improve --> Create
    Deploy --> Retire[Retire old version]

Idea utama, yang dibawa dari Pelajaran 10: penilaian luar talian adalah pintu keselamatan, bukan pemikiran selepas. Versi ejen baru tidak dihantar melainkan ia melepasi ambang penilaian anda. Kebolehlihatan dalam talian kemudian memberi maklum balas kegagalan dunia sebenar ke dalam set ujian luar talian anda. Itulah gelung keseluruhannya.

Strategi Penskalaan

Penskalaan ejen berbeza daripada penskalaan API web tanpa status, kerana setiap permintaan boleh mencetus panggilan model dan alat yang mahal banyak kali. Empat teknik membawa sebahagian besar beban.

Pengendalian permintaan tanpa status. Jangan simpan keadaan per pengguna dalam memori proses anda. Kekalkan utas perbualan dalam stor utas Foundry atau perkhidmatan memori supaya mana-mana instance boleh mengendalikan mana-mana permintaan. Ini membolehkan anda skala secara mendatar — tambah instance, tiada sesi melekit.

Penentuan laluan model. Tidak setiap permintaan memerlukan model paling canggih (dan paling mahal) anda. Hantar permintaan mudah — pengelasan niat, jawapan fakta ringkas — ke model kecil dan cepat, dan simpan model besar untuk penalaran sebenar. Model Router Foundry boleh melakukan ini untuk anda, atau anda boleh melaksanakan pengelasan ringan sendiri. Anda akan bina versi DIY dalam makmal.

Caching respons. Banyak pertanyaan sokongan adalah hampir serupa (“bagaimana saya reset kata laluan?”). Simpan jawapan kepada soalan biasa dan hidangkan tanpa perlu panggil model langsung. Walaupun kadar cache hit sederhana mengurangkan kos dan latensi dengan ketara.

Keserentakan dan tekanan belakang. Pembekal model mempunyai had kadar. Hadkan keserentakan anda, gunakan cubaan semula dengan penangguhan eksponen, dan gagal dengan anggun (respons “kami sedang urus” yang diatur dalam antrian lebih baik daripada ralat 500).

flowchart LR
    Q[User query] --> C{Cache hit?}
    C -->|yes| R[Return cached answer]
    C -->|no| Router{Complexity?}
    Router -->|simple| SLM[Small model]
    Router -->|complex| LLM[Large model]
    SLM --> Out[Response]
    LLM --> Out
    Out --> Store[Cache + trace]

Kebolehlihatan Dalam Pengeluaran

Anda tidak dapat mengendalikan apa yang anda tidak dapat lihat. Seperti yang dibincangkan dalam Pelajaran 10, Microsoft Agent Framework mengeluarkan jejak OpenTelemetry secara asli — setiap panggilan model, panggilan alat, dan langkah orkestrasi menjadi satu span. Dalam pengeluaran, anda mengeksport span itu ke Microsoft Foundry (atau mana-mana backend yang serasi OTel) supaya anda boleh:

from agent_framework.observability import get_tracer

tracer = get_tracer()

with tracer.start_as_current_span("support_request") as span:
    span.set_attribute("customer.tier", "enterprise")
    span.set_attribute("routed.model", "gpt-5-nano")
    # agent execution is traced automatically inside this span

Atribut seperti customer.tier dan routed.model adalah apa yang menukar tembok jejak menjadi soalan yang boleh dijawab (“adakah pelanggan perusahaan sering diarahkan ke model kecil?”).

Pengoptimuman Kos

Kos dalam ejen pengeluaran didominasi oleh token. Tiga tuil, mengikut susunan impak:

  1. Saiz model yang betul. Model kecil yang melepasi pintu penilaian anda hampir sentiasa lebih murah daripada model besar yang juga melepasi. Gunakan penilaian untuk membuktikan model kecil cukup baik daripada memilih model terbesar sebagai langkah berjaga-jaga.
  2. Penentuan laluan mengikut kerumitan. Seperti di atas — bayar harga model besar hanya untuk permintaan yang memerlukan penalaran model besar.
  3. Cache secara agresif. Panggilan model termurah adalah yang tidak pernah anda buat.

Pintu penilaian dan kawalan kos adalah disiplin yang sama dilihat dari dua sudut: penilaian memberitahu anda lantai kualiti, penentuan laluan dan caching memastikan anda sedekat mungkin kepada kos lantai tersebut.

Pertimbangan Penyebaran Enterprise

Tadbir urus. Hosted Agents mewarisi RBAC, keselamatan kandungan, dan log audit Foundry. Beri setiap ejen identiti terurus dengan keistimewaan paling minimum yang diperlukan — akses baca sahaja ke pangkalan pengetahuan, akses bertumpu ke API tiket, tiada lebih.

Manusia dalam gelung. Beberapa tindakan terlalu besar kesannya untuk diotomasi sepenuhnya — mengeluarkan balik duit, memadam akaun, meningkatkan kepada pasukan undang-undang. Microsoft Agent Framework menyokong alat yang memerlukan kelulusan: ejen mencadangkan tindakan, pelaksanaan berhenti, manusia meluluskan atau menolak, dan aliran kerja disambung semula. Anda lihat asasannya dalam Pelajaran 6; di sini anda menyebarkannya.

MCP dalam pengeluaran. MCP membenarkan ejen anda menggunakan alat luaran melalui antara muka standard. Dalam pengeluaran, anggap setiap pelayan MCP sebagai sempadan yang tidak dipercayai: pin versi pelayan, jalankan dengan identiti tertumpu, sahkan output, dan jangan dedahkan rahsia kepadanya. Pelayan MCP adalah kebergantungan, dan kebergantungan perlu dikemas kini, diaudit, dan dihadkan kadar.

flowchart TB
    subgraph Dev[Development Architecture]
        D1[Notebook] --> D2[Agent Framework]
        D2 --> D3[Model Provider]
        D2 --> D4[Local tools]
    end
    subgraph Deploy[Deployment Architecture]
        E1[CI pipeline] --> E2[Evaluation gate]
        E2 -->|pass| E3[Foundry Agent Service]
        E3 --> E4[Versioned hosted agent]
    end
    subgraph Run[Runtime Architecture]
        F1[Client app] --> F2[Hosted agent]
        F2 --> F3[Model Router]
        F2 --> F4[Azure AI Search RAG]
        F2 --> F5[Memory service]
        F2 --> F6[MCP tools]
        F2 --> F7[OTel -> Foundry tracing]
        F2 --> F8[Human approval]
    end

Tiga rajah itu — pembangunan, penyebaran, masa jalan — adalah ejen yang sama pada tiga peringkat hayatnya. Makmal yang berikut akan membimbing anda membinanya.

Makmal Praktikal: Ejen Sokongan Pelanggan Sedia untuk Pengeluaran

Buka code_samples/16-python-agent-framework.ipynb dan jalankan ia dari awal hingga akhir. Anda akan membina ejen sokongan pelanggan Contoso dengan setiap keperluan pengeluaran bersambung:

  1. Panggilan alat — semak status pesanan dan buka tiket sokongan.
  2. RAG — jawab soalan polisi dari pangkalan pengetahuan (Azure AI Search, dengan fallback dalam memori supaya buku nota berjalan tanpa sumber Search).
  3. Memori — ingat pelanggan sepanjang pusingan perbualan.
  4. Penentuan laluan model — pengelas kerumitan menghantar setiap permintaan ke model kecil atau besar.
  5. Caching respons — soalan berulang dilayan dari cache.
  6. Kelulusan manusia — pengembalian wang di atas ambang berhenti untuk kelulusan manusia.
  7. Saluran penilaian — set ujian luar talian kecil menilai ejen dan bertindak sebagai pintu pelepasan.
  8. Kebolehlihatan — penjejakan OpenTelemetry di sekitar setiap permintaan.

Panduan

Buku nota disusun supaya setiap keperluan pengeluaran adalah bahagian yang berdiri sendiri dan boleh dijalankan. Intinya adalah pengendali permintaan routing-plus-caching:

async def handle_support_request(query: str, customer_id: str) -> str:
    # 1. Serve from cache when we can.
    cached = response_cache.get(normalize(query))
    if cached:
        return cached

    # 2. Route by complexity to control cost.
    model = "gpt-5-nano" if is_simple(query) else "gpt-5-mini"

    # 3. Run the agent inside a trace span for observability.
    with tracer.start_as_current_span("support_request") as span:
        span.set_attribute("routed.model", model)
        span.set_attribute("customer.id", customer_id)
        response = await support_agent.run(query, model=model)

    # 4. Cache and return.
    response_cache.set(normalize(query), response.text)
    return response.text

Pintu penilaian yang menjaga pelepasan kelihatan seperti ini:

async def evaluation_gate(agent, test_cases, threshold: float = 0.8) -> bool:
    passed = 0
    for case in test_cases:
        result = await agent.run(case["input"])
        if score_response(result.text, case["expected"]) >= 0.8:
            passed += 1
    pass_rate = passed / len(test_cases)
    print(f"Evaluation pass rate: {pass_rate:.0%} (gate: {threshold:.0%})")
    return pass_rate >= threshold  # only deploy if the gate passes

Baca setiap baris — buku nota mengekalkan asasannya kecil dengan sengaja supaya tiada yang tersembunyi di belakang panggilan kerangka.

Mengesahkan Ejen yang Disebarkan dengan Ujian Asap

Pintu penilaian di atas dijalankan luar talian terhadap objek ejen anda. Setelah ejen disebarkan sebagai Hosted Agent, anda memerlukan satu lagi pemeriksaan, yang lebih murah: adakah titik akhir yang disebarkan benar-benar menjawab?

Penyebaran “berjaya” hanya membuktikan pesawat kawalan menerima definisi — ia tidak membuktikan ejen memberi respons. Kebergantungan yang hilang, penentuan laluan model salah, atau sambungan tamat boleh meninggalkan penyebaran hijau yang tidak memberi apa-apa jawapan. Ujian asap menangkap itu dalam beberapa saat, pada setiap penyebaran, tanpa kos penilaian penuh.

Repositori ini menyediakan saluran ujian asap sedia guna yang dibina atas GitHub Action AI Smoke Test:

- name: Smoke-test hosted agent
  uses: JFolberth/ai-smoketest@v1
  with:
    project_endpoint: $
    agent_name: ContosoSupportAgent
    tests_file: tests/lesson-16-smoke-tests.json

Jalankan dari tab Actions setelah ejen anda diterapkan, dengan membekalkan endpoint projek Foundry anda dan nama ejen. Identiti persekutuan memerlukan peranan Azure AI User pada skop projek Foundry. Fikirkan lapisan seperti piramid: ujian asap (boleh dicapai dan bertindak balas?) dijalankan pada setiap penerapan, penilaian luar talian (cukup baik untuk dihantar?) dijalankan sebelum promosi, dan penilaian dalam talian (bagaimana prestasinya di alam nyata?) dijalankan secara berterusan.

Semakan Pengetahuan

Uji pemahaman anda sebelum bergerak ke tugasan.

1. Anggaran berapa banyak daripada ejen produksi adalah “model,” dan apa selebihnya?

Jawapan Model adalah minoriti sistem — sering dikatakan sekitar 20%. Selebihnya adalah kerangka operasi: penghosan dan pengurusan versi, identiti dan RBAC, keadaan terluar, pengendalian kegagalan, penjejakan kos, penilaian, dan kawalan manusia-dalam-laluan. Berpindah ke produksi kebanyakannya mengenai membina segala sesuatu *sekitar* gelung penaakulan.

2. Bila anda akan memilih Hosted Agent berbanding ejen yang dihoskan klien?

Jawapan Apabila anda mahukan runtime yang diurus dengan ketahanan terbina dalam (benang yang berterusan dan boleh disambung semula), kemampuan pemerhatian, keselamatan kandungan, dan RBAC, dan anda sanggup bertukar kawalan tahap rendah gelung penaakulan untuk mengurangkan kawasan operasi. Klien dihoskan adalah lebih baik apabila anda memerlukan kawalan penuh ke atas gelung atau menggabungkan ejen dalam backend sedia ada.

3. Mengapa ejen yang boleh diskala mesti tanpa keadaan dalam memori prosesnya sendiri?

Jawapan Supaya mana-mana instans boleh mengendalikan mana-mana permintaan, yang membolehkan skala mendatar tanpa sesi melekit. Keadaan perbualan per pengguna diterluarkan ke penyimpanan benang atau perkhidmatan memori. Jika keadaan tinggal dalam memori proses, anda akan kehilangannya apabila dimulakan semula dan tidak boleh mengedarkan beban dengan bebas.

4. Masalah apa yang diselesaikan oleh penghalaan model, dan bagaimana ia berkaitan dengan penilaian?

Jawapan Penghalaan menghantar permintaan mudah kepada model kecil yang murah dan pantas dan mengekalkan model besar untuk penaakulan sebenar, mengawal kedua-dua latensi dan kos. Ia berkaitan dengan penilaian kerana penilaian adalah apa yang *membuktikan* model kecil itu cukup baik untuk kelas permintaan — penghalaan tanpa penilaian adalah meneka.

5. Apakah “pagar penilaian” dan di manakah ia berada dalam kitar hayat?

Jawapan Pagar penilaian menjalankan set ujian luar talian terhadap versi ejen baru dan menghalang penerapan melainkan kadar lulus melepasi ambang. Ia berada di antara "versi" dan "terapkan" dalam kitar hayat, menjadikan kualiti satu syarat untuk pelepasan dan bukan sesuatu yang anda semak selepas penghantaran.

6. Mengapa pelayan MCP harus dianggap sebagai sempadan yang tidak dipercayai dalam produksi?

Jawapan Kerana ia adalah pergantungan luaran yang ejen anda panggil. Anda harus mengepit versinya, jalankan dengan identiti berkawalan skop, sahkan keluarannya, hadkan kadar, dan jangan dedahkan rahsia kepadanya — disiplin yang sama anda gunakan untuk mana-mana pergantungan pihak ketiga. Keluaran daripadanya mengalir ke penaakulan ejen anda, jadi kepercayaan tanpa sah adalah risiko keselamatan.

7. Perubahan tunggal mana yang biasanya mempunyai impak terbesar pada kos ejen produksi, dan mengapa?

Jawapan Menyesuaikan saiz model — menggunakan model terkecil yang masih melepasi pagar penilaian anda. Kos didominasi oleh token, dan model yang lebih kecil yang memenuhi bar kualiti hampir selalu lebih murah daripada yang lebih besar. Caching dan penghalaan kemudian mengurangkan kos lebih jauh, tetapi memilih model asas yang betul mempunyai kesan utama pertama.

8. Peranan atribut jarak seperti customer.tier dan routed.model dalam pemerhatian?

Jawapan Mereka mengubah jejak mentah menjadi soalan perniagaan yang boleh dijawab. Tanpa atribut anda mempunyai dinding jarak; dengan mereka, anda boleh bertanya "adakah pelanggan perniagaan sedang sering dihantar ke model kecil?" atau "model mana yang mengendalikan permintaan kami yang paling perlahan?" Atribut adalah cara anda menghiris telemetri mengikut dimensi yang penting untuk operasi anda.

Tugasan

Ambil ejen sokongan pelanggan dari makmal dan kuatkan untuk senario khusus: ejen sokongan bil langganan untuk syarikat SaaS.

Penyerahan anda harus:

  1. Gantikan alat dengan yang berkaitan bil: get_subscription_status, get_invoice, dan issue_credit (kredit melebihi $50 memerlukan kelulusan manusia).
  2. Tambah tiga dokumen RAG yang merangkumi polisi pemulangan, kitaran bil, dan polisi pembatalan syarikat.
  3. Perluas set penilaian kepada sekurang-kurangnya lapan kes, termasuk sekurang-kurangnya dua yang perlu mencetuskan laluan kelulusan manusia, dan sahkan pagar penilaian anda lulus atau gagal dengan betul.
  4. Tambah satu laporan kos: selepas menjalankan sepuluh pertanyaan campuran melalui ejen, cetak berapa banyak yang dihantar ke model kecil, berapa banyak kepada model besar, dan berapa banyak yang dilayani dari cache.

Tulis perenggan pendek (dalam sel markdown) menerangkan peraturan penghalaan model yang anda pilih dan bagaimana anda akan mengesahkannya dengan trafik sebenar. Tiada jawapan tunggal yang betul — anda dinilai berdasarkan sama ada kebimbangan produksi dipasang bersama secara serasi.

Rumusan

Dalam pelajaran ini anda mengalihkan ejen dari prototaip ke produksi dengan Microsoft Foundry:

Pelajaran seterusnya mengambil perjalanan bertentangan: bukannya menskalakan ejen ke awan, anda akan membawanya turun ke mesin pembangun tunggal dan menjalankannya sepenuhnya secara tempatan.

Sumber Tambahan

Pelajaran Sebelumnya

Membangun Ejen Penggunaan Komputer (CUA)

Pelajaran Seterusnya

Mewujudkan Ejen AI Tempatan

Penafian: Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI Co-op Translator. Walaupun kami berusaha untuk ketepatan, sila ambil maklum bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang sahih. Untuk maklumat penting, terjemahan oleh manusia profesional adalah disyorkan. Kami tidak bertanggungjawab terhadap sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini.

This site is open source. Improve this page.