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 - Non-interactive credential forwarding for tool calls that require PSCredential - 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). -ToolCredential Optional PSCredential passed to the agent runtime for non-interactive tool execution. When provided, this credential is securely exported to a temp CLIXML file, passed to the child runtime process, and cleaned up after the run. Tools with a Credential parameter can consume it automatically. -ToolCredentialVariableName Optional variable name to resolve a session/global PSCredential when -ToolCredential is not supplied. Defaults to 'dac'. Example: if $dac contains PSCredential, Invoke-TechAgent will use it automatically for tool calls that support Credential. -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. - For non-interactive auth, prefer -ToolCredential or a PSCredential stored in the variable named by -ToolCredentialVariableName (default: $dac). - Avoid embedding "-Credential $dac" inside prompt text. Provide credential context through Invoke-TechAgent parameters instead. 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. Example 5: $dac = Get-Credential Invoke-TechAgent "Disable only AD user jdoe. Use Disable-User with WhatIf and return markdown results." -Mode execute -ConfirmDestructive -ToolCredential $dac Description ----------- Runs a destructive-capable workflow while supplying PSCredential non-interactively for tools that require Credential. Example 6: $dac = Get-Credential Invoke-TechAgent "Disable only AD user jdoe. Use Disable-User with WhatIf and return markdown results." -Mode execute -ConfirmDestructive Description ----------- Uses the default variable name ($dac) via -ToolCredentialVariableName 'dac' when -ToolCredential is omitted. SEE ALSO - about_TechToolbox - Initialize-TechToolboxRuntime - Get-FilesUsingKeywords - Clear-BrowserProfileData - Disable-User |