en-US/about_Invoke-TechAgent.help.txt
|
about_Invoke-TechAgent
TOPIC about_Invoke-TechAgent SHORT DESCRIPTION Sends a natural-language prompt to the TechToolbox local agent and returns the agent's response. LONG DESCRIPTION Invoke-TechAgent is the primary entry point for interacting with the TechToolbox Python-based automation agent. It accepts a prompt string, validates configuration, launches the underlying tech_agent.py process, and waits for completion while managing transcripts, markdown logs, and error handling. The function supports: - Selecting an Ollama model (validated against locally available models) - Configuring iteration limits and wait timeouts - Explicitly authorizing destructive operations - Managing console transcripts and structured markdown run logs - Automatic retry on recursion limits PARAMETERS -Prompt (Mandatory) The natural-language instruction for the agent. Must not be null or empty. This is passed directly to the Python agent as the --prompt argument. -Model Optional Ollama model name (e.g., llama3, mistral, qwen2.5-coder). If specified, the function validates the model exists locally via `ollama list`. If omitted, defaults to the model configured in TechToolbox settings ($script:cfg.settings.agent.model) or the agent's default model. -MaxIterations Integer between 1 and 500, default 15. Limits the maximum number of tool/ reasoning iterations before the agent concludes. The wait timeout is calculated as MaxIterations * 180 seconds (minimum 300 seconds), unless overridden by config settings ($cfg.wait.timeoutSeconds). -Quiet Legacy compatibility switch. Agent traces are now suppressed by default. -ConfirmDestructive Explicitly authorizes destructive operations for this run. Passes the --destructive-confirmed flag to the Python agent and logs a warning message: "Destructive operations explicitly authorized for this run." -SignedFilePolicy Sets how the agent handles overwriting existing Authenticode-signed PowerShell files. Allowed values: - ignore: Block overwrite when a signature block is detected. - strip: Allow overwrite and strip signature block text. Passes --signed-file-policy to the Python agent. -AutoRetryOnRecursion Enables automatic retry when the Python agent hits a recursion limit. Passes --auto-retry-on-recursion to the Python agent. -DisableAutoRetryOnRecursion Disables recursion-limit auto-retry for this invocation, overriding environment defaults. Passes --no-auto-retry-on-recursion to the Python agent. Mutually exclusive with -AutoRetryOnRecursion; using both will throw an exception. -NoTranscript Disables the per-run console transcript log. By default, transcripts are enabled and written to LogsAndExports\Logs\TechAgentTranscripts unless overridden by config settings ($cfg.transcript.enabled or $cfg.transcript.outputRoot). INPUTS String (Prompt parameter) OUTPUTS System.String - The trimmed stdout output from the agent on success. NOTES - Resolves the Python executable from a local .venv first, then falls back to system python or py launcher. - Configures wait timeout/polling based on MaxIterations and config settings. Default poll interval is 5 seconds; heartbeat interval is 60 seconds. - Writes structured markdown logs to LogsAndExports\Logs\TechAgentMarkdown containing status, timestamps, prompt, output, errors, and exit codes. - Requires Python (python, py, or venv python) available on PATH or in .venv. - Requires Ollama installed and accessible on PATH when -Model is used. - Uses async stream readers to avoid redirected-pipe deadlocks. - Terminates the agent process on timeout or failure. EXAMPLES Example 1: Invoke-TechAgent "Run system diagnostics and summarize findings." Description ----------- Sends a prompt to the default model and returns the response. Example 2: Invoke-TechAgent "Clean up old temporary files" -Model qwen2.5-coder -MaxIterations 30 Description ----------- Sends a prompt using a specific Ollama model with an increased iteration limit. Example 3: Invoke-TechAgent "Delete all users in OU=Test" -ConfirmDestructive Description ----------- Sends a prompt and explicitly authorizes destructive operations for this run. Example 4: Invoke-TechAgent "Update Public/Get/Get-ToolboxHelp.ps1" -ConfirmDestructive -SignedFilePolicy strip Description ----------- Allows overwrite of an Authenticode-signed PowerShell file by stripping the signature block during write. SEE ALSO - about_TechToolbox - Initialize-TechToolboxRuntime - Get-FilesUsingKeywords - Clear-BrowserProfileData - Disable-User |