Shell-eszközök

A béta agent-framework-tools Python csomag rendszerhéj-végrehajtást és környezettudatos eszközöket biztosít a agent_framework.tools névtéren keresztül.

Eszköz	Akkor használja, ha
LocalShellTool	A parancsok megbízhatók vagy egyedileg jóváhagyottak, és az ügynökfolyamat gazdakörnyezetében kell futniuk.
DockerShellTool	A modell által létrehozott rendszerhéjparancsok OCI-tároló elkülönítését igénylik.
ShellEnvironmentProvider	A modellnek szüksége van az aktív shellcsalád, az operációs rendszer, a munkakönyvtár és a telepített CLI-eszközök verzióinak adataira.
ShellPolicy	A jóváhagyás vagy a végrehajtás előtt egy engedélyezési vagy megtagadási listát szeretne előszűrni.

Warning

A rendszerhéj végrehajtása módosíthatja a fájlokat, elindíthatja a folyamatokat, hozzáférhet a hitelesítő adatokhoz, és kommunikálhat a külső rendszerekkel. Használja a feladatot támogató legkevésbé kiemelt végrehajtási szintet.

A csomag telepítése

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

A helyi parancsértelmező és a környezet ismeretének használata

LocalShellExecutor állapot nélküli és állandó üzemmódokat támogat. ShellEnvironmentProvider felméri az aktív környezetet, és irányadó, shellre vonatkozó útmutatást ad az ügynök kontextusához.

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 parancselőszűréshez is elérhető. Egy dedikált futtatható DockerShellExecutor minta jelenleg nincs közzétéve.

A csomag telepítése

pip install agent-framework-tools --pre

A csomag a psutil elemet telepíti a gyermekfolyamatok fájának leállításához, ha egy végrehajtás túllépi az időkorlátot.

Használja a LocalShellTool-t

A(z) LocalShellTool parancsok közvetlenül a gazdagépen futnak. Alapértelmezés szerint perzisztens rendszerhéjat, 30 másodperces időtúllépést, a kimenet 64 KiB-nál történő csonkolását, a munkakönyvtárra való korlátozást és minden parancs jóváhagyását használja.

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())

Akkor használható mode="stateless" , ha minden hívásnak egy új folyamatban kell futnia. A meghatározott shell felülbírálásához használja a AGENT_FRAMEWORK_SHELL környezeti változót vagy a shell konstruktorargumentumot.

Important

LocalShellTool nem tesztkörnyezet. A jóváhagyás az elsődleges biztonsági határ. A jóváhagyás letiltásához acknowledge_unsafe=True szükséges.

Parancsok korlátozása a(z) ShellPolicy használatával

ShellPolicy a végrehajtás előtt alkalmazza a reguláris kifejezés engedélyezésére és elutasítására vonatkozó listákat. A megtagadási szabályok elsőbbséget élveznek.

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

A parancsszabályzatok használhatósági előszűrők, nem biztonsági határok. A shell szintaxisa, aliasai, változói, értelmezői és kódolt adatcsomagjai megkerülhetik az egyszerű mintailesztést.

Adj hozzá ShellEnvironmentProvider

ShellEnvironmentProvider felderíti a shellcsaládot, a verziót, az operációs rendszert, a munkakönyvtárat és a kiválasztott CLI-verziókat, majd még azelőtt beilleszti ezt az információt, hogy az ügynök elindulna. Az alapértelmezett mintavételi lista: git, nodepythonés 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)

Használja a DockerShellTool-t

DockerShellTool használatához Docker vagy Podman szükséges a következőn: PATH. Az alapértelmezett beállítások letiltják a hálózatkezelést, nem gyökérfelhasználóként futnak, írásvédett legfelső szintű fájlrendszert használnak, képességeket csökkentenek, 512 MiB-re korlátozzák a memóriát, és 256 folyamatra korlátozzák a tárolót.

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)

Az alapértelmezett kép a következő mcr.microsoft.com/azurelinux/base/core:3.0. A Podman használatához adja meg a(z) docker_binary="podman" értéket. Egy dedikált futtatható DockerShellTool minta jelenleg nincs közzétéve.

Végrehajtási szint kiválasztása

Scenario	Eszköz	Elkülönítési határ
Megbízható fejlesztési parancsok	LocalShellTool	Jóváhagyás a gazdaprocesszben
Nem megbízható shellparancsok	DockerShellTool	OCI-tároló alapértelmezett elkülönítési jelzőkkel
Nem megbízható forrásból származó generált kód shell nélkül	Hyperlight CodeAct	Hyperlight microVM

A Go helyi parancsértelmező-végrehajtást és környezetvizsgálatot tesz lehetővé a(z) tool/shelltool révén. Lásd: A helyi parancsértelmező eszköz használata.

DockerShellTool Az útmutató jelenleg nem érhető el a Go számára.

Shelleszközök használata a Harness Agenttel

Az egyszerű ügynökök és a HarnessAgent ugyanazt a kétrészes rendszerhéj-beállítást használják: regisztrálja a végrehajtó függvényét eszközként, és adja hozzá a ShellEnvironmentProvider elemet, amikor a modellnek meg kell kapnia a rendszerhéjjal, az operációs rendszerrel, a munkakönyvtárral és a CLI-verzióval kapcsolatos környezetet. HarnessAgent nem hoz létre shellvégrehajtót, és nem is rendelkezik vele:

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 alapértelmezés szerint a run_shell és requireApproval: true nevet használja. LocalShellExecutor alapértelmezés szerint állandó mód, kimeneti streamenként 64 KiB-korlát, időtúllépés nélkül; a példa kifejezetten az ajánlott 30 másodpercet LocalShellExecutor.DefaultTimeouthasználja. ShellEnvironmentProviderOptions alapértelmezés szerint a következőket vizsgálja: git, dotnet, node, python és docker, vizsgálatonként öt másodperces időtúllépéssel.

Hozzon létre egy állandó végrehajtót felhasználói munkamenetenként, és helyezze el a munkamenet végén. Ne ossza meg felhasználók vagy párhuzamos beszélgetések között, mert a munkakönyvtár, a környezet, a shell-előzmények, a háttérfeladatok és a parancsvárólista közösek. ShellPolicy csak előszűrés; hagyja engedélyezve a jóváhagyást, használja a legkevésbé kiemelt hitelesítő adatokat, és előnyben részesítse DockerShellExecutor , ha a parancsok erősebb elkülönítési határt igényelnek.

A parancsértelmező eszközök az előzetes kiadású Microsoft.Agents.AI.Tools.Shell csomagban érhetők el. HarnessAgent elérhető innen: Microsoft.Agents.AI.Harness.

Egyszerű ügynök esetén hozza létre a shellfüggvényt a(z) client.get_shell_tool(func=shell.as_function()) használatával, és a(z) ShellEnvironmentProvider elemet külön adja hozzá. create_harness_agent mindkét lépést végrehajtja, ha átadja a(z) shell_executor paramétert:

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 igény szerinti, és elérhetővé kell tennie as_function(). A gyártó csak akkor adja hozzá a shelleszközt és a(z) ShellEnvironmentProvider elemet, ha a kliens megvalósítja a(z) SupportsShellTool elemet; ellenkező esetben figyelmeztetést naplóz, és mindkettőt kihagyja. A(z) shell_environment_provider_options nem kötelező, és csak a(z) shell_executor elemmel együtt használható.

LocalShellTool alapértelmezés szerint perzisztens módot, 30 másodperces időtúllépést, 64 KiB-os egyesített kimenetet, a munkakönyvtár újbóli rögzítését és approval_mode="always_require" használ. Mivel a Harness eszköz jóváhagyása alapértelmezés szerint engedélyezve van, adjon át egy AgentSession elemet a következőnek: run. A hívóé a végrehajtó életciklusa; használjon async with vagy hívjon close(), és hozzon létre egy állandó eszközt felhasználói munkamenetenként. Ne ossza meg a módosítható shellállapotot a felhasználók vagy a párhuzamos beszélgetések között.

A gazdarendszer parancsértelmezője nem elkülönített környezet. Hagyja engedélyezve a jóváhagyást, használja a legkevésbé kiemelt hitelesítő adatokat, és használja DockerShellTool a tárolóelkülönítéshez. A jóváhagyás letiltása megköveteli approval_mode="never_require" , és acknowledge_unsafe=Truea ; ShellPolicy önmagában nem biztonsági határ.

create_harness_agent a következőben jelenik meg: agent-framework-core A héjintegrációt az előzetes kiadású agent-framework-tools csomag biztosítja, és engedélyezéskor egy ExperimentalWarning jelet bocsát ki.

A csomagolt Go Harness jelenleg nem érhető el. Állítsa össze a helyi shelleszközt és a környezeti szolgáltatót közvetlenül egy egyszerű Go-ügynökre.

Kapcsolódó útmutatók

• Eszköz jóváhagyása
• Ügynökhám
• Hyperlight