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