AiAgent.h header

#include <ew/app/AiAgent.h>

Namespace ew::app

AiAgentResult struct

struct ew::app::AiAgentResult

The outcome of an agent conversation: the final answer (or an error) plus a log of the tools the agent used to reach it (for transparency in the UI).

Members

bool ew::app::AiAgentResult::ok = false

True when the agent produced an answer; false when a request errored.

QString ew::app::AiAgentResult::answer

The agent's final answer (when ok).

QStringList ew::app::AiAgentResult::toolLog

The tool calls the agent made, in order, each as "name(arguments)".

QString ew::app::AiAgentResult::error

A human-readable error (when not ok).

TokenUsage ew::app::AiAgentResult::usage {}

The token usage summed across every model call the agent made (all zero when the provider reported none).

Types

using ew::app::AgentToolExecutor = std::function<QString(const AiToolCall&)>

A pluggable tool executor: returns the tool-result text for one call. Read-only agents execute against a WorldSnapshot; act-mode agents marshal the call to the GUI thread, apply it through the undoable command stack, and return the outcome text.

Functions

AiAgentResult ew::app::runAgentConversation(AiProvider &provider, const std::vector< AiToolSpec > &tools, const AgentToolExecutor &executor, const QString &systemPrompt, const QString &question, int maxSteps=6)

Generalized agent loop: asks provider the question under systemPrompt with tools attached, running every tool call through executor and feeding the results back until the model answers or maxSteps tool rounds are spent. The snapshot overload below is this with the read-only world tools; act mode (docs/AI_FOLDER_CONVERSION.md §4b) passes read+write tools and an executor that mutates the live project on the GUI thread. Blocking (it drives the provider); call off the GUI thread — the executor may itself marshal back onto it.

AiAgentResult ew::app::runAgentConversation(AiProvider &provider, const WorldSnapshot &world, const QString &question, int maxSteps=6)

Runs an agentic conversation: asks provider the question with the read-only world tools (see AiAgentTools) attached, executing each tool call the model makes against the world snapshot and feeding the results back, until the model answers or maxSteps tool rounds are spent. provider is the caller's configured AI and must speak OpenAI-compatible function-calling; world is a copyable snapshot (see snapshotWorld), so this is safe to run off the GUI thread. Returns the final answer and the tool log, or an error. Blocking (it drives the provider), so call it off the GUI thread.

AiAgentResult ew::app::runAgentWith(const AiSettings &settings, const WorldSnapshot &world, const QString &question, int maxSteps=6)

Convenience entry point: builds an HttpAiProvider from settings and runs runAgentConversation over the world snapshot for question. It constructs the provider itself, so a background task needs only value-copyable inputs (settings, snapshot, question). Blocking; call off the GUI thread.