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 packaged TechToolbox local automation agent runtime. It accepts a prompt string, validates configuration, launches the TechToolbox.Agent C# runtime, 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 - Loading persistent memory from AI\memory.json by default - Learning lightweight user preferences, facts, and recent run history - 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 TechToolbox.Agent runtime. -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 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 the selected policy to the TechToolbox.Agent runtime. -AutoRetryOnRecursion Enables automatic retry when the C# agent hits an iteration limit. -DisableAutoRetryOnRecursion Disables recursion-limit auto-retry for this invocation, overriding environment defaults. 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). -AutoPromptHint When preflight warnings or critical findings are present, prints a preflight-ready prompt rewrite suggestion to help improve prompt quality on the next run. This does not change the current run's prompt. -AutoRerunFromHint Performs one preflight rewrite pass using the generated prompt hint when prompt quality is weak, then continues the current run using that rewritten prompt. INPUTS String (Prompt parameter) OUTPUTS System.String - The trimmed stdout output from the agent on success. NOTES - Prefers the packaged AgentRuntime\TechToolbox.Agent\TechToolbox.Agent.dll when present, then falls back to local development build outputs under src. - Uses persistent memory by default at AI\memory.json unless agent.memoryPath is overridden in TechToolbox config. - The memory layer stores lightweight preferences, facts, and recent run history to improve follow-up prompts without requiring a separate service. - 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 Ollama installed and accessible on PATH when -Model is used. - Launches the C# runtime in a fresh child pwsh process to avoid stale DLL reuse and PowerShell assembly conflicts. - Uses async stream readers to avoid redirected-pipe deadlocks. - Terminates the child 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 |