Alat shell

Paket Python beta agent-framework-tools menyediakan alat eksekusi shell dan kesadaran lingkungan melalui agent_framework.tools namespace layanan.

Alat Gunakan saat
LocalShellTool Perintah tepercaya atau disetujui secara individual dan harus berjalan di lingkungan host proses agen.
DockerShellTool Perintah shell yang dihasilkan model memerlukan isolasi kontainer OCI.
ShellEnvironmentProvider Model ini membutuhkan keluarga shell aktif, sistem operasi, direktori kerja, dan versi CLI yang diinstal.
ShellPolicy Anda menginginkan pra-filter daftar izinkan atau tolak daftar sebelum persetujuan atau eksekusi.

Warning

Eksekusi shell dapat memodifikasi file, meluncurkan proses, mengakses kredensial, dan berkomunikasi dengan sistem eksternal. Gunakan tingkat eksekusi paling tidak istimewa yang mendukung tugas.

Pasang paketnya 

dotnet add package Microsoft.Agents.AI.Tools.Shell --prerelease

Menggunakan shell lokal dan kesadaran lingkungan

LocalShellExecutor mendukung mode stateless dan persisten. ShellEnvironmentProvider menyelidiki lingkungan aktif dan menambahkan panduan shell otoritatif ke konteks agen.

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Tools.Shell;
using Microsoft.Extensions.AI;

var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";

// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
var aiProjectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());

const string Instructions = """
    You are an agent with a single tool: run_shell. Use it to satisfy the
    user's request. Do not describe what you would do — actually run the
    commands. Reply with the final answer derived from real output.
    """;

// --------------------------------------------------------------------
// 1. Stateless mode — each call gets a fresh shell.
// --------------------------------------------------------------------
Console.WriteLine("### Stateless mode\n");
await using (var statelessShell = new LocalShellExecutor(new() { Mode = ShellMode.Stateless, AcknowledgeUnsafe = true }))
{
    var envProvider = new ShellEnvironmentProvider(statelessShell);
    var statelessAgent = aiProjectClient.AsAIAgent(new ChatClientAgentOptions
    {
        ChatOptions = new()
        {
            ModelId = deploymentName,
            Instructions = Instructions,
            Tools = [statelessShell.AsAIFunction(requireApproval: false)],
        },
        AIContextProviders = [envProvider],
    });
// --------------------------------------------------------------------
// 2. Persistent mode — one shell, reused across calls. State carries.
// --------------------------------------------------------------------
Console.WriteLine("\n### Persistent mode\n");
await using (var persistentShell = new LocalShellExecutor(new() { Mode = ShellMode.Persistent, AcknowledgeUnsafe = true }))
{
    var envProvider = new ShellEnvironmentProvider(persistentShell);
    var persistentAgent = aiProjectClient.AsAIAgent(new ChatClientAgentOptions
    {
        ChatOptions = new()
        {
            ModelId = deploymentName,
            Instructions = Instructions,
            Tools = [persistentShell.AsAIFunction(requireApproval: false)],
        },
        AIContextProviders = [envProvider],
    });

    var persistentSession = await persistentAgent.CreateSessionAsync();

    // State carries across calls in persistent mode: cd into temp, then
    // verify the next call sees the new CWD.
    Console.WriteLine(await persistentAgent.RunAsync("Change directory into the system temp folder, then print the current working directory.", persistentSession));
    Console.WriteLine();
    Console.WriteLine(await persistentAgent.RunAsync("In a NEW shell call, print the current working directory again. Tell me whether it still matches the temp folder.", persistentSession));
    Console.WriteLine();

    // Same idea with an exported variable: set in one call, read in the next.
    Console.WriteLine(await persistentAgent.RunAsync("Set the environment variable DEMO_TOKEN to the value 'hello-world'.", persistentSession));
    Console.WriteLine();
    Console.WriteLine(await persistentAgent.RunAsync("Print the current value of DEMO_TOKEN. Tell me exactly what value the shell reports.", persistentSession));
    Console.WriteLine();

    PrintSnapshot(envProvider.CurrentSnapshot!);
}

ShellPolicy juga tersedia untuk pra-pemfilteran perintah. Sampel khusus yang dapat DockerShellExecutor dijalankan saat ini tidak diterbitkan.

Pasang paketnya 

pip install agent-framework-tools --pre

Paket diinstal psutil untuk mengakhiri pohon proses anak ketika waktu eksekusi habis.

Gunakan LocalShellTool

LocalShellTool menjalankan perintah langsung di host. Ini default ke shell persisten, batas waktu 30 detik, pemotongan output 64 KiB, kurungan direktori kerja, dan persetujuan untuk setiap perintah.

import asyncio
from typing import Any

from agent_framework import Agent, Message
from agent_framework.openai import OpenAIChatClient
from agent_framework.tools import LocalShellTool
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()
async def main() -> None:
    print("=== OpenAI Agent with LocalShellTool Example ===")
    print("NOTE: Commands will execute on your local machine.\n")

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

    async with LocalShellTool() as shell:
        agent = Agent(
            client=client,
            instructions="You are a helpful assistant that can run shell commands to help the user.",
            tools=[client.get_shell_tool(func=shell.as_function())],
        )

        query = "Use the shell tool to execute `python --version` and show only the command output."
        print(f"User: {query}")
        result = await run_with_approvals(query, agent)
        if isinstance(result, str):
            print(f"Agent: {result}\n")
            return
        if result.text:
            print(f"Agent: {result.text}\n")
        else:
            printed = False
            for message in result.messages:
                for content in message.contents:
                    if content.type == "function_result" and content.result:
                        print(f"Agent (tool output): {content.result}\n")
                        printed = True
            if not printed:
                print("Agent: (no text output returned)\n")


async def run_with_approvals(query: str, agent: Agent) -> Any:
    """Run the agent and handle shell approvals outside tool execution."""
    current_input: str | list[Any] = query

    while True:
        result = await agent.run(current_input)
        if not result.user_input_requests:
            return result

        next_input: list[Any] = [query]
        rejected = False
        for user_input_needed in result.user_input_requests:
            if user_input_needed.function_call is None:
                continue
            print(
                f"\nShell request: {user_input_needed.function_call.name}"
                f"\nArguments: {user_input_needed.function_call.arguments}"
            )
            user_approval = await asyncio.to_thread(input, "\nApprove shell command? (y/n): ")
            approved = user_approval.strip().lower() == "y"
            next_input.append(Message("assistant", [user_input_needed]))
            next_input.append(Message("user", [user_input_needed.to_function_approval_response(approved)]))
            if not approved:
                rejected = True
                break
        if rejected:
            print("\nShell command rejected. Stopping without additional approval prompts.")
            return "Shell command execution was rejected by user."
        current_input = next_input


if __name__ == "__main__":
    asyncio.run(main())

Gunakan mode="stateless" saat setiap panggilan harus berjalan dalam proses baru. AGENT_FRAMEWORK_SHELL Gunakan variabel lingkungan atau shell argumen konstruktor untuk mengambil alih shell yang diselesaikan.

Important

LocalShellTool bukan kotak pasir. Persetujuan adalah batas keamanan utama. Menonaktifkan persetujuan memerlukan acknowledge_unsafe=True.

Batasi perintah dengan ShellPolicy

ShellPolicy menerapkan daftar izinkan dan tolak ekspresi reguler sebelum eksekusi. Aturan penolakan lebih diutamakan.

import asyncio

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient
from agent_framework.tools import LocalShellTool, ShellPolicy
from dotenv import load_dotenv
load_dotenv()
async def main() -> None:
    client = OpenAIChatClient(model="gpt-5.4-nano")

    shell = LocalShellTool(
        mode="stateless",
        approval_mode="never_require",
        acknowledge_unsafe=True,
        policy=ShellPolicy(
            allowlist=[
                r"^ls(\s|$)",
                r"^pwd$",
                r"^cat\s[^|;&]+$",
                r"^git\s+(status|log|diff)(\s|$)",
                r"^python\s+--version$",
            ],
        ),
        timeout=10,
    )

    agent = Agent(
        client=client,
        instructions=(
            "You can run a narrow set of read-only shell commands (ls, pwd, cat, "
            "git status/log/diff, python --version). Anything else will be rejected."
        ),
        tools=[client.get_shell_tool(func=shell.as_function())],
    )

    query = "Summarise the current directory and print the Python version."
    print(f"User: {query}")
    result = await agent.run(query)
    print(f"Agent: {result.text}")

Warning

Kebijakan perintah adalah pra-filter kegunaan, bukan batas keamanan. Sintaks shell, alias, variabel, interpreter, dan payload yang dikodekan dapat melewati pencocokan pola sederhana.

Tambahkan ShellEnvironmentProvider

ShellEnvironmentProvider menyelidiki keluarga shell, versi, sistem operasi, direktori kerja, dan versi CLI yang dipilih, lalu menyuntikkan informasi tersebut sebelum agen berjalan. Daftar pemeriksaan default adalah git, , nodepython, dan docker.

import asyncio

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient
from agent_framework.tools import (
    LocalShellTool,
    ShellEnvironmentProvider,
    ShellEnvironmentProviderOptions,
)
from dotenv import load_dotenv
load_dotenv()
def _print_snapshot(label: str, provider: ShellEnvironmentProvider) -> None:
    snapshot = provider.current_snapshot
    if snapshot is None:
        print(f"[{label}] no snapshot captured")
        return
    print(f"\n[{label}] snapshot:")
    print(f"  family            = {snapshot.family.value}")
    print(f"  os                = {snapshot.os_description}")
    print(f"  shell_version     = {snapshot.shell_version}")
    print(f"  working_directory = {snapshot.working_directory}")
    for tool, version in snapshot.tool_versions.items():
        print(f"  {tool:<17} = {version}")


async def _ask(agent: Agent, query: str) -> None:
    print(f"\nUser: {query}")
    result = await agent.run(query)
    if result.text:
        print(f"Agent: {result.text}")


async def main() -> None:
    client = OpenAIChatClient(model="gpt-5.4-nano")
    options = ShellEnvironmentProviderOptions(
        probe_tools=("git", "python", "uv", "node"),
    )

    print("=== stateless mode ===")
    async with LocalShellTool(
        mode="stateless",
        approval_mode="never_require",
        acknowledge_unsafe=True,
    ) as shell:
        provider = ShellEnvironmentProvider(shell, options)
        agent = Agent(
            client=client,
            instructions="Use the shell tool to answer the user's question.",
            tools=[client.get_shell_tool(func=shell.as_function())],
            context_providers=[provider],
        )
        await _ask(agent, "Show me the current working directory.")
        await _ask(agent, "Now `cd ..` then show the working directory again.")
        await _ask(agent, "Show the working directory once more — did `cd` persist?")
        _print_snapshot("stateless", provider)

    print("\n=== persistent mode ===")
    async with LocalShellTool(
        mode="persistent",
        confine_workdir=False,
        approval_mode="never_require",
        acknowledge_unsafe=True,
    ) as shell:
        provider = ShellEnvironmentProvider(shell, options)
        agent = Agent(
            client=client,
            instructions="Use the shell tool to answer the user's question.",
            tools=[client.get_shell_tool(func=shell.as_function())],
            context_providers=[provider],
        )
        await _ask(agent, "Show me the current working directory.")
        await _ask(agent, "Now `cd ..` then show the working directory again.")
        await _ask(agent, "Show the working directory once more — did `cd` persist?")
        _print_snapshot("persistent", provider)

Gunakan DockerShellTool

DockerShellTool memerlukan Docker atau Podman pada PATH. Default menonaktifkan jaringan, menjalankan sebagai pengguna non-root, menggunakan sistem file akar baca-saja, menghilangkan kemampuan, membatasi memori hingga 512 MiB, dan menutup kontainer pada 256 proses.

from agent_framework.tools import DockerShellTool

async with DockerShellTool(
    image="mcr.microsoft.com/azurelinux/base/core:3.0",
    approval_mode="never_require",
) as shell:
    result = await shell.run("uname -a && id")
    print(result.stdout)

Gambar defaultnya adalah mcr.microsoft.com/azurelinux/base/core:3.0. Teruskan docker_binary="podman" untuk menggunakan Podman. Sampel khusus yang dapat DockerShellTool dijalankan saat ini tidak diterbitkan.

Pilih tingkat eksekusi

Skenario Alat Batas isolasi
Perintah pengembangan tepercaya LocalShellTool Persetujuan dalam proses host
Perintah shell yang tidak tepercaya DockerShellTool Kontainer OCI dengan bendera isolasi default
Kode yang dihasilkan tidak tepercaya tanpa shell Hyperlight CodeAct MikroVM hyperlight

Go menyediakan eksekusi shell lokal dan pemeriksaan lingkungan melalui tool/shelltool. Lihat Menggunakan alat shell lokal.

DockerShellTool panduan saat ini tidak tersedia untuk Go.

Menggunakan alat shell dengan Harness Agent

Agen biasa dan HarnessAgent gunakan penyiapan shell dua bagian yang sama: daftarkan fungsi pelaksana sebagai alat, dan tambahkan ShellEnvironmentProvider kapan model harus menerima shell, sistem operasi, direktori kerja, dan konteks versi CLI. HarnessAgent tidak membuat atau memiliki pelaksana shell:

using System.IO;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Tools.Shell;
using Microsoft.Extensions.AI;

await using var shell = new LocalShellExecutor(new LocalShellExecutorOptions
{
    WorkingDirectory = Directory.GetCurrentDirectory(),
    Timeout = LocalShellExecutor.DefaultTimeout,
});

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    AIContextProviders = [new ShellEnvironmentProvider(shell)],
    ChatOptions = new ChatOptions
    {
        Tools = [shell.AsAIFunction(requireApproval: true)],
    },
});

AsAIFunction default ke nama run_shell dan requireApproval: true. LocalShellExecutor default ke mode persisten, batas 64 KiB per aliran output, dan tanpa batas waktu; contoh secara eksplisit menggunakan 30 detik LocalShellExecutor.DefaultTimeoutyang direkomendasikan . ShellEnvironmentProviderOptions default untuk memeriksa git, , dotnet, node, pythondan docker, dengan batas waktu lima detik per pemeriksaan.

Buat satu eksekutor persisten per sesi pengguna dan buang saat sesi berakhir. Jangan bagikan di seluruh pengguna atau percakapan bersamaan karena direktori kerja, lingkungan, riwayat shell, pekerjaan latar belakang, dan antrean perintah dibagikan. ShellPolicy hanya pra-filter; pertahankan persetujuan diaktifkan, gunakan kredensial yang paling tidak istimewa, dan lebih suka DockerShellExecutor ketika perintah memerlukan batas isolasi yang lebih kuat.

Alat shell tersedia dari paket prarilis Microsoft.Agents.AI.Tools.Shell . HarnessAgent tersedia dari Microsoft.Agents.AI.Harness.

Untuk agen biasa, buat fungsi shell dengan client.get_shell_tool(func=shell.as_function()) dan tambahkan ShellEnvironmentProvider secara terpisah. create_harness_agent melakukan kedua langkah saat Anda lulus shell_executor:

from agent_framework import create_harness_agent
from agent_framework.tools import LocalShellTool, ShellEnvironmentProviderOptions

async with LocalShellTool() as shell:
    agent = create_harness_agent(
        client=client,
        shell_executor=shell,
        shell_environment_provider_options=ShellEnvironmentProviderOptions(
            probe_tools=("git", "python"),
        ),
    )

    session = agent.create_session()
    response = await agent.run("Inspect the current repository.", session=session)

shell_executor adalah keikutsertaan dan harus mengekspos as_function(). Pabrik menambahkan alat shell dan ShellEnvironmentProvider hanya ketika klien mengimplementasikan SupportsShellTool; jika tidak, itu mencatat peringatan dan melompati keduanya. shell_environment_provider_options bersifat opsional dan hanya digunakan dengan shell_executor.

LocalShellTool default ke mode persisten, batas waktu 30 detik, output gabungan 64 KiB, re-anchoring direktori kerja, dan approval_mode="always_require". Karena persetujuan alat Harness diaktifkan secara default, teruskan AgentSession ke run. Pemanggil memiliki siklus hidup pelaksana; gunakan async with atau panggil close(), dan buat satu alat persisten per sesi pengguna. Jangan bagikan status shell yang dapat diubah di seluruh pengguna atau percakapan bersamaan.

Shell host bukan kotak pasir. Pertahankan persetujuan diaktifkan, gunakan kredensial yang paling tidak istimewa, dan gunakan DockerShellTool untuk isolasi kontainer. Menonaktifkan persetujuan memerlukan approval_mode="never_require" dan acknowledge_unsafe=True; ShellPolicy saja bukan batas keamanan.

create_harness_agent dirilis dalam agent-framework-core. Integrasi shell disediakan oleh paket pra-rilis agent-framework-tools dan memancarkan ExperimentalWarning saat diaktifkan.

Go Harness paket saat ini tidak tersedia. Buat alat shell lokal dan penyedia lingkungan langsung di agen Go biasa.

  • Last updated on