Ordfoss

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::ai::agent::AiAgentResult::ok = false

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

QString ew::app::ai::agent::AiAgentResult::answer

The agent's final answer (when ok). Empty when exhausted.

bool ew::app::ai::agent::AiAgentResult::exhausted = false

True when the loop spent its whole step budget without the model producing an answer.

Reported rather than papered over with a sentence of its own: libs/app has no translation catalogue, so a message written here would reach a Spanish writer in English, and a caller that could not tell "answered" from "gave up" had no way to say anything better (F-0101). The client decides what to show, in the user's language.

QStringList ew::app::ai::agent::AiAgentResult::toolLog

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

QString ew::app::ai::agent::AiAgentResult::error

A human-readable error (when not ok).

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

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

Types

using ew::app::ai::agent::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::ai::agent::runAgentContinuation(app::ai::AiProvider &provider, const std::vector< AiToolSpec > &tools, const AgentToolExecutor &executor, const std::vector< AiMessage > &conversation, int maxSteps=6)

The same, continuing conversation instead of starting from one question.

conversation is the exchange so far, oldest first, including its leading system turn; the loop appends its own assistant and tool turns to a copy and never touches the caller's.

The single-question overload above gives the model amnesia between requests, which is wrong for anything conversational: a writer who says "summarize the documents", is misunderstood, and then says "no, the documents, not the entities" was talking to an assistant that had never seen the first two turns and could not take the correction. Tool results from earlier turns are deliberately NOT carried – only the visible exchange – so a stale reading of an object the assistant has since changed cannot be mistaken for current data.

AiAgentResult ew::app::ai::agent::runAgentConversation(app::ai::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. Spending the budget returns AiAgentResult::ok with AiAgentResult::exhausted set and no answer; a maxSteps of zero or less is that case immediately, without a request. 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.