Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
O pacote Python beta agent-framework-tools fornece ferramentas de execução em shell e consciência ambiental através do agent_framework.tools namespace.
| Tool | Use-o quando |
|---|---|
LocalShellTool |
Os comandos são confiáveis ou aprovados individualmente e devem ser executados no ambiente anfitrião do processo agente. |
DockerShellTool |
Os comandos shell gerados por modelos necessitam de isolamento de contentores OCI. |
ShellEnvironmentProvider |
O modelo necessita da família de shell ativa, do sistema operativo, do diretório de trabalho e das versões de CLI instaladas. |
ShellPolicy |
Quer um pré-filtro de lista de permitir ou de rejeitar antes da aprovação ou execução. |
Warning
A execução shell pode modificar ficheiros, iniciar processos, aceder a credenciais e comunicar com sistemas externos. Use o nível de execução menos privilegiado que suporte a tarefa.
Instale o pacote
dotnet add package Microsoft.Agents.AI.Tools.Shell --prerelease
Use a concha local e a consciência ambiental
LocalShellExecutor suporta modos sem estado e persistentes.
ShellEnvironmentProvider sonda o ambiente ativo e adiciona orientação autoritativa do shell ao contexto do agente.
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 também está disponível para pré-filtragem por comandos. Uma amostra dedicada e DockerShellExecutor executável não está atualmente publicada.
Instale o pacote
pip install agent-framework-tools --pre
O pacote instala-se para terminar árvores de processos filhos quando uma execução expira psutil .
Utilize LocalShellTool
LocalShellTool executa comandos diretamente no anfitrião. Por defeito, utiliza um shell persistente, um timeout de 30 segundos, truncamento de saída de 64 KiB, confinamento de diretórios de trabalho e aprovação para cada comando.
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())
Use mode="stateless" quando cada chamada deve ser executada num processo novo. Use a AGENT_FRAMEWORK_SHELL variável de ambiente ou o shell argumento construtor para sobrescrever o shell resolvido.
Importante
LocalShellTool não é um sandbox. A aprovação é o principal limite de segurança. Desativar a aprovação requer acknowledge_unsafe=True.
Comandos de restrição com ShellPolicy
ShellPolicy Aplica listas de permitir e negar em expressões regulares antes da execução. As regras de negação têm prioridade.
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
Uma política de comando é um pré-filtro de usabilidade, não um limite de segurança. Sintaxe shell, aliases, variáveis, interpretadores e cargas úteis codificadas podem contornar o simples ajuste de padrões.
Adicionar ShellEnvironmentProvider
ShellEnvironmentProvider sonda a família de shell, versão, sistema operativo, diretório de trabalho e versões selecionadas da CLI, depois injeta essa informação antes da execução do agente. A lista padrão de sondas é git, node, python, e 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)
Utilize DockerShellTool
DockerShellTool requer Docker ou Podman em PATH. Os valores definidos desativam a rede, executam como utilizador não-root, usam um sistema de ficheiros raiz apenas de leitura, reduzem capacidades, limitam a memória a 512 MiB e limitam o contentor a 256 processos.
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)
A imagem padrão é mcr.microsoft.com/azurelinux/base/core:3.0. Passe docker_binary="podman" para usar o Podman. Uma amostra dedicada e DockerShellTool executável não está atualmente publicada.
Escolha um nível de execução
| Scenario | Tool | Limite de isolamento |
|---|---|---|
| Comandos de desenvolvimento confiáveis | LocalShellTool |
Aprovação no processo de anfitrião |
| Comandos shell não confiáveis | DockerShellTool |
Contentor OCI com flags de isolamento por defeito |
| Código gerado sem confiança sem shell | Hyperlight CodeAct | MicroVM hiperleve |
O Go fornece execução local em shell e sondagem ambiental através tool/shelltoolde . Veja Usar a ferramenta local shell.
DockerShellTool a orientação não está disponível para o Go.
Use ferramentas shell com o Harness Agent
Agentes simples e HarnessAgent usam a mesma configuração de shell em duas partes: registar a função do executor como uma ferramenta e adicionar ShellEnvironmentProvider quando o modelo deve receber shell, sistema operativo, diretório de trabalho e contexto da versão CLI.
HarnessAgent não cria nem possui um executor de 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 por defeito, o nome run_shell e requireApproval: true.
LocalShellExecutor por defeito para o modo persistente, um limite de 64 KiB por fluxo de saída e sem timeout; O exemplo usa explicitamente os 30 LocalShellExecutor.DefaultTimeoutsegundos recomendados .
ShellEnvironmentProviderOptionspor defeito, sonda git, dotnet, nodepython, , e docker, com um tempo de espera de cinco segundos por sonda.
Crie um executor persistente por sessão de utilizador e elimine-o quando a sessão terminar. Não partilhes entre utilizadores ou conversas simultâneas porque diretórios de trabalho, ambiente, histórico de shell, trabalhos em segundo plano e a fila de comandos são partilhados.
ShellPolicy é apenas um pré-filtro; Mantenha a aprovação ativada, use credenciais com privilégios mínimos e prefira DockerShellExecutor quando os comandos exigem uma fronteira de isolamento mais forte.
As ferramentas shell estão disponíveis no pacote de pré-lançamento Microsoft.Agents.AI.Tools.Shell .
HarnessAgent está disponível em Microsoft.Agents.AI.Harness.
Para um agente simples, crie a função shell com client.get_shell_tool(func=shell.as_function()) e adicione ShellEnvironmentProvider separadamente.
create_harness_agent Realiza ambos os passos quando passa 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 é opt-in e deve expor as_function(). A fábrica adiciona a ferramenta shell e ShellEnvironmentProvider só quando o cliente implementa SupportsShellTool; caso contrário, regista um aviso e salta ambos.
shell_environment_provider_options é opcional e é usado apenas com shell_executor.
LocalShellTool por defeito para modo persistente, um timeout de 30 segundos, saída combinada de 64 KiB, reancoragem do diretório de trabalho, e approval_mode="always_require". Como a aprovação da ferramenta harness está ativada por defeito, passe um AgentSession para run. O chamador detém o ciclo de vida do executor; Use async with ou chame close(), e crie uma ferramenta persistente por sessão de utilizador. Não partilhe estados mutáveis do shell entre utilizadores ou conversas simultâneas.
A concha do host não é um sandbox. Mantenha a aprovação ativada, use credenciais com privilégios mínimos e use DockerShellTool para isolamento de contentores. Desativar a aprovação requer approval_mode="never_require" e acknowledge_unsafe=True; ShellPolicy sozinho não é um limite de segurança.
create_harness_agent é libertado em agent-framework-core. A integração com shell é fornecida pelo pacote pré-lançamento agent-framework-tools e emite um ExperimentalWarning quando ativado.
Um Go Harness embalado não está atualmente disponível. Escreva a ferramenta local de shell e o serviço de ambiente diretamente num agente Straight.