api-reference.md

API Reference

This page is a compact reference for the main public types in the agent module. It is meant for lookup after the main concepts are already clear.

The stable runtime surface is centered on:

Agent::run(const AgentRequest &request)

An agent run is configured through AgentConfig, described through AgentRequest, executed by Agent, and returned as an AgentResponse.

Header

Use the public Vix AI aggregator in normal application code:

#include <vix/ai.hpp>

For examples that print output:

#include <vix/print.hpp>

For lower-level runtime code, direct agent headers can also be used:

#include <vix/ai/agent/AgentRuntime.hpp>

Namespace

The lower-level agent runtime lives in:

namespace vix::ai::agent

Most runtime types on this page are under that namespace.

Agent

Agent is the main runtime object. It receives an AgentRequest, prepares the run, calls the configured provider, executes allowed tools when needed, and returns an AgentResponse.

vix::ai::agent::Agent agent(config);

auto result = agent.run(request);

Constructors

Agent(const AgentConfig &config);

Creates an agent from a configuration. When the provider is ollama, the runtime can create the default Ollama provider from the configuration.

Agent(
    const AgentConfig &config,
    std::shared_ptr<ModelProvider> provider);

Creates an agent with an injected provider. This is useful for tests, custom providers, and advanced integrations.

Main operation

AgentResult<AgentResponse> run(const AgentRequest &request);

Runs one agent request.

Example:

auto result = agent.run(request);

if (!result)
{
  vix::print("Agent error:", result.error().message());
  return 1;
}

vix::print(result.value().text);

Tools

ToolRegistry &tools();

Returns the tool registry used by the agent. Advanced code can use this to register custom tools.

auto err = agent.tools().add(std::make_shared<MyTool>());

if (err)
{
  vix::print("Tool error:", err.message());
}

AgentConfig

AgentConfig controls the runtime policy of an agent instance.

vix::ai::agent::AgentConfig config;

Provider fields

Field	Type	Purpose
`provider`	`std::string`	Provider name, usually `ollama`.
`model`	`std::string`	Model name passed to the provider.
`model_url`	`std::string`	Provider endpoint, usually `http://127.0.0.1:11434` for Ollama.

Example:

config.provider = "ollama";
config.model = "llama3";
config.model_url = "http://127.0.0.1:11434";

Timeout fields

Field	Type	Purpose
`timeout_ms`	integer	Model request timeout in milliseconds.
`tool_timeout_ms`	integer	Tool execution timeout in milliseconds.

Example:

config.timeout_ms = 120'000;
config.tool_timeout_ms = 30'000;

Workspace and context limits

Field	Type	Purpose
`max_files`	integer	Maximum number of files collected by a project scan.
`max_file_size`	integer	Maximum file size accepted for agent context.
`max_context_chars`	integer	Maximum prepared context size.
`max_tool_output`	integer	Maximum output returned by a tool.
`max_tool_rounds`	integer	Maximum number of model/tool loop rounds.

Example:

config.max_files = 2'000;
config.max_file_size = 512 * 1024;
config.max_context_chars = 120'000;
config.max_tool_output = 20'000;
config.max_tool_rounds = 3;

Permission fields

Field	Type	Purpose
`allow_file_read`	`bool`	Allows the runtime to read safe files inside the workspace.
`allow_process`	`bool`	Allows controlled command execution.
`allow_file_write`	`bool`	Reserved for file-writing capability. Disabled by default.
`allowed_programs`	list of strings	Programs allowed by `command.run`.

Example:

config.allow_file_read = true;
config.allow_process = false;
config.allow_file_write = false;

Command execution requires an allowlist:

config.allow_process = true;

config.allowed_programs = {
    "vix",
    "cmake",
    "ninja",
    "git",
    "echo"
};

Cache and persistence fields

Field	Type	Purpose
`use_cache`	`bool`	Enables local response cache when the request also allows it.
`cache_ttl_ms`	integer	Cache time-to-live in milliseconds.
`persist_memory`	`bool`	Enables local run history and memory persistence.
`offline`	`bool`	Describes the local-first runtime policy.

Example:

config.use_cache = true;
config.cache_ttl_ms = 5 * 60 * 1000;
config.persist_memory = true;
config.offline = true;

AgentConfigLoader

AgentConfigLoader builds an AgentConfig from environment variables.

auto config = vix::ai::agent::AgentConfigLoader::from_environment();

The default prefix is:

VIX_AGENT_

Common variables:

VIX_AGENT_PROVIDER
VIX_AGENT_MODEL
VIX_AGENT_MODEL_URL
VIX_AGENT_MEMORY_DIR
VIX_AGENT_CACHE_DIR
VIX_AGENT_RUNS_DIR
VIX_AGENT_LOGS_DIR
VIX_AGENT_TIMEOUT_MS
VIX_AGENT_MAX_FILES
VIX_AGENT_MAX_FILE_SIZE
VIX_AGENT_MAX_TOOL_OUTPUT
VIX_AGENT_MAX_CONTEXT_CHARS
VIX_AGENT_OFFLINE
VIX_AGENT_ALLOW_PROCESS
VIX_AGENT_ALLOW_FILE_READ
VIX_AGENT_ALLOW_FILE_WRITE
VIX_AGENT_USE_CACHE
VIX_AGENT_PERSIST_MEMORY

Example:

auto config = vix::ai::agent::AgentConfigLoader::from_environment();

config.model = "qwen2.5-coder:1.5b";
config.timeout_ms = 120'000;

AgentConfigValidator

AgentConfigValidator validates an agent configuration before a run.

auto err = vix::ai::agent::AgentConfigValidator::validate(config);

if (err)
{
  vix::print("Invalid config:", err.message());
  return 1;
}

Validation is useful when configuration is loaded from the environment, command-line flags, or project files.

AgentRequest

AgentRequest describes one agent run.

vix::ai::agent::AgentRequest request;

Main fields

Field	Type	Purpose
`workspace`	`std::string`	Workspace directory for the run.
`input`	`std::string`	Main user prompt or instruction.
`context`	`std::string`	Optional extra context supplied by the application.
`mode`	`AgentRequestMode`	High-level request mode.
`model_override`	`std::string`	Optional model override for one request.
`timeout_ms`	integer	Optional request timeout.

Example:

request.workspace = ".";
request.input = "Explain this project in simple words.";
request.mode = vix::ai::agent::AgentRequestMode::Analyze;
request.timeout_ms = 120'000;

Permission fields

Field	Type	Purpose
`allow_tools`	`bool`	Allows the model/tool loop for this request.
`allow_file_read`	`bool`	Allows file-reading tools for this request.
`allow_process`	`bool`	Allows command execution for this request.
`allow_file_write`	`bool`	Allows file-writing capability when supported.
`use_cache`	`bool`	Allows cache for this request.

Example:

request.allow_tools = true;
request.allow_file_read = true;
request.allow_process = false;
request.allow_file_write = false;
request.use_cache = true;

The request can restrict the configuration for one run. It should not be used to bypass a capability disabled in AgentConfig.

AgentRequestMode

AgentRequestMode gives the request a high-level purpose.

request.mode = vix::ai::agent::AgentRequestMode::Run;
request.mode = vix::ai::agent::AgentRequestMode::Analyze;
request.mode = vix::ai::agent::AgentRequestMode::Explain;
request.mode = vix::ai::agent::AgentRequestMode::Chat;

Mode	Purpose
`Run`	General agent task.
`Analyze`	Analyze a workspace or project.
`Explain`	Explain a concept, file, API, or behavior.
`Chat`	Normal prompt without project analysis.

AgentResponse

AgentResponse is returned by Agent::run.

const auto &response = result.value();

Fields

Field	Type	Purpose
`text`	`std::string`	Final response text.
`run_id`	`std::string`	Local run identifier.
`provider`	`std::string`	Provider that produced the response.
`model`	`std::string`	Model used for the response.
`from_cache`	`bool`	Whether the response came from cache.
`duration_ms`	integer	Run duration in milliseconds.
`tools`	list	Tool summaries from the run.

Example:

vix::print(response.text);
vix::print("Run id:", response.run_id);
vix::print("Provider:", response.provider);
vix::print("Model:", response.model);
vix::print("From cache:", response.from_cache);
vix::print("Duration:", response.duration_ms, "ms");

Tool summaries:

vix::print("Tools used:", response.tools.size());

for (const auto &tool : response.tools)
{
  vix::print("-", tool.name, tool.ok ? "ok" : "failed");
}

AgentResult

Agent operations return AgentResult<T>.

auto result = agent.run(request);

Always check the result before reading the value.

if (!result)
{
  vix::print("Agent error:", result.error().message());
  return 1;
}

vix::print(result.value().text);

AgentResult<T> follows the Vix result style and carries structured errors instead of forcing failures into response text.

AgentWorkspace

AgentWorkspace represents the local boundary of a run.

auto workspace = vix::ai::agent::AgentWorkspace::open(".", config);

if (!workspace)
{
  vix::print("Workspace error:", workspace.error().message());
  return 1;
}

The workspace is used for path resolution, project scanning, file tools, command working directories, cache, run history, and local agent data.

Default local directories:

.vix/agent/memory
.vix/agent/cache
.vix/agent/runs
.vix/agent/logs

FileScanPolicy

FileScanPolicy decides which files are useful and safe for agent context.

vix::ai::agent::FileScanPolicy policy(config);

It applies file limits, filters common generated directories, and rejects unsupported or unsafe files.

Common ignored paths include:

.git
.vix
.cache
.idea
.vscode
build
build-ninja
cmake-build-debug
cmake-build-release
node_modules
vendor
dist
out
target
__pycache__

ProjectScanner

ProjectScanner scans a workspace using a FileScanPolicy.

vix::ai::agent::ProjectScanner scanner(workspace.value(), policy);

auto scan = scanner.scan();

Example:

if (!scan)
{
  vix::print("Scan error:", scan.error().message());
  return 1;
}

vix::print("Workspace:", scan.value().root);
vix::print("Files:", scan.value().files.size());
vix::print("Skipped:", scan.value().skipped);
vix::print("Truncated:", scan.value().truncated ? "yes" : "no");

FileReader

FileReader reads safe text files from a workspace.

vix::ai::agent::FileReader reader(workspace.value(), policy);

It is used by the file.read tool. Paths are resolved through the workspace and checked by policy before content is returned.

ModelProvider

ModelProvider is the interface for model backends.

class MyProvider final : public vix::ai::agent::ModelProvider
{
public:
  [[nodiscard]] std::string_view name() const noexcept override;
  [[nodiscard]] bool local() const noexcept override;

  [[nodiscard]] vix::ai::agent::AgentResult<bool>
  available() const override;

  [[nodiscard]] vix::ai::agent::AgentResult<vix::ai::agent::ModelResponse>
  generate(const vix::ai::agent::ModelRequest &request) override;
};

Providers should generate model responses. They should not execute local tools directly.

ModelRequest

ModelRequest is sent from the agent runtime to a provider.

Important fields include:

Field	Purpose
`model`	Model name.
`prompt`	Prepared prompt text.
`system_prompt`	Optional system prompt.
`messages`	Optional message list.
`max_tokens`	Optional generation limit.
`timeout_ms`	Request timeout.
`stream`	Stream preference.
`options`	Provider-specific options.

Simple provider usage:

vix::ai::agent::ModelResponse response;

response.text = "Generated response.";
response.model = request.model;
response.provider = "my-provider";
response.status = vix::ai::agent::ModelResponseStatus::Completed;

ModelResponse

ModelResponse is returned by a provider.

Important fields include:

Field	Purpose
`text`	Generated text.
`model`	Model name.
`provider`	Provider name.
`status`	Response status.
`error`	Provider error text when applicable.
`duration_ms`	Provider duration.
`usage`	Token or usage information when available.
`tool_calls`	Tool calls requested by the model.
`raw`	Raw provider data when useful.

A successful response should set:

response.text = "Hello from provider.";
response.model = request.model;
response.provider = "my-provider";
response.status = vix::ai::agent::ModelResponseStatus::Completed;

ModelResponseStatus

ModelResponseStatus describes the provider response state.

Common successful status:

response.status = vix::ai::agent::ModelResponseStatus::Completed;

A provider should not return a successful-looking response when generation failed. Provider failures should be returned through AgentResult.

OllamaProvider

OllamaProvider is the default local model provider.

vix::ai::agent::AgentConfig config;

config.provider = "ollama";
config.model = "llama3";
config.model_url = "http://127.0.0.1:11434";

auto provider =
    std::make_shared<vix::ai::agent::OllamaProvider>(config);

Check availability:

auto available = provider->available();

if (!available || !available.value())
{
  vix::print("Ollama is not available.");
  vix::print("Start it with: ollama serve");
  return 1;
}

The provider sends requests to:

POST /api/generate

Tool

Tool is the interface for runtime tools.

class MyTool final : public vix::ai::agent::Tool
{
public:
  [[nodiscard]] std::string_view name() const noexcept override;
  [[nodiscard]] std::string_view description() const noexcept override;

  [[nodiscard]] vix::ai::agent::AgentResult<vix::ai::agent::ToolResult>
  run(const vix::ai::agent::ToolCall &call) override;
};

Tools should be small, explicit, and tied to the permissions of the application that registers them.

ToolRegistry

ToolRegistry stores tools by name.

auto err = agent.tools().add(std::make_shared<MyTool>());

if (err)
{
  vix::print("Tool error:", err.message());
}

The agent uses the registry when a provider response contains tool calls.

ToolCall

ToolCall represents one requested tool operation.

Important fields include:

Field	Purpose
`id`	Tool call identifier.
`name`	Tool name.
`reason`	Optional reason for the call.
`arguments`	JSON arguments passed to the tool.

Example:

vix::ai::agent::ToolCall call;

call.id = "tool_echo_1";
call.name = "command.run";
call.reason = "Run a safe command.";

With arguments:

call.arguments = vix::json::Json::object();
call.arguments["program"] = "echo";
call.arguments["args"] = vix::json::Json::array();
call.arguments["args"].push_back("hello");
call.arguments["working_directory"] = ".";

ToolResult

ToolResult represents the result of a tool call.

Important fields include:

Field	Purpose
`id`	Tool call id.
`name`	Tool name.
`ok`	Whether the tool succeeded.
`output`	Tool output.
`error`	Tool error message.
`duration_ms`	Tool duration.
`data`	Optional structured data.

A tool can return success:

return vix::ai::agent::ToolResult::success(
    call.id,
    "test.echo",
    "echo");

Or failure:

return vix::ai::agent::ToolResult::failure(
    call.id,
    "test.echo",
    "tool failed");

FileReadTool

FileReadTool implements:

file.read

Expected arguments:

{
  "path": "src/main.cpp"
}

It reads a safe text file inside the workspace. The path is resolved through AgentWorkspace and checked by FileScanPolicy.

CommandTool

CommandTool implements:

command.run

Expected arguments:

{
  "program": "vix",
  "args": ["build"],
  "working_directory": "."
}

Command execution requires:

config.allow_process = true;
request.allow_process = true;
request.allow_tools = true;

It also requires the program to be present in config.allowed_programs.

config.allowed_programs = {
    "vix",
    "cmake",
    "ninja",
    "git",
    "echo"
};

The working directory must stay inside the workspace.

AgentRunStore

AgentRunStore writes local run history under the workspace.

Default run directory:

.vix/agent/runs/<run_id>/

A run may include:

run.json
prompt.txt
model_response.json
tools.json
response.json
response.txt
error.json

Most applications do not need to call AgentRunStore directly. It is used by the runtime when persistence is enabled.

config.persist_memory = true;

AgentRunTimer

AgentRunTimer measures run duration and timestamps for agent execution. It is used internally by the runtime and run history.

Most applications read timing through AgentResponse:

vix::print("Duration:", response.duration_ms, "ms");

AgentId

AgentId creates identifiers used by agent runs and tool calls.

Common ids include:

run id
tool call id
operation id

Most applications use the returned response.run_id rather than creating ids manually.

AgentFingerprint

AgentFingerprint creates hashes used for cache keys and fingerprints.

Common uses include:

file fingerprint
prompt fingerprint
model response cache key
tool cache key

This is part of the cache and run-history infrastructure. Applications usually do not need it unless they are extending the runtime.

Error names

Agent-specific error names include:

empty_input
invalid_workspace
path_outside_workspace
model_unavailable
model_request_failed
model_response_invalid
tool_not_found
tool_not_allowed
tool_failed
tool_timeout
memory_unavailable
memory_write_failed
memory_read_failed
config_invalid
internal_failure

Always read the error message from the result:

if (!result)
{
  vix::print("Agent error:", result.error().message());
  return 1;
}

Complete example

The following example shows the core public runtime workflow.

#include <vix/ai.hpp>
#include <vix/print.hpp>

int main()
{
  vix::ai::agent::AgentConfig config;

  config.provider = "ollama";
  config.model = "llama3";
  config.model_url = "http://127.0.0.1:11434";

  config.timeout_ms = 120'000;

  config.allow_file_read = true;
  config.allow_process = false;
  config.allow_file_write = false;

  config.use_cache = true;
  config.persist_memory = true;

  auto err = vix::ai::agent::AgentConfigValidator::validate(config);

  if (err)
  {
    vix::print("Invalid config:", err.message());
    return 1;
  }

  vix::ai::agent::Agent agent(config);

  vix::ai::agent::AgentRequest request;

  request.workspace = ".";
  request.input = "Explain the structure of this project.";
  request.mode = vix::ai::agent::AgentRequestMode::Analyze;

  request.allow_tools = true;
  request.allow_file_read = true;
  request.allow_process = false;
  request.allow_file_write = false;
  request.use_cache = true;
  request.timeout_ms = config.timeout_ms;

  auto result = agent.run(request);

  if (!result)
  {
    vix::print("Agent error:", result.error().message());
    return 1;
  }

  const auto &response = result.value();

  vix::print(response.text);
  vix::print();
  vix::print("Run id:", response.run_id);
  vix::print("Provider:", response.provider);
  vix::print("Model:", response.model);
  vix::print("From cache:", response.from_cache);
  vix::print("Duration:", response.duration_ms, "ms");

  return 0;
}

Next step

Use this page as a lookup reference while reading the more detailed pages for configuration, workspace, model providers, tools, cache, errors, and CMake integration.

Uh oh!

FilesExpand file tree

api-reference.md

Latest commit

History

api-reference.md

File metadata and controls

API Reference

Header

Namespace

Agent

Constructors

Main operation

Tools

AgentConfig

Provider fields

Timeout fields

Workspace and context limits

Permission fields

Cache and persistence fields

AgentConfigLoader

AgentConfigValidator

AgentRequest

Main fields

Permission fields

AgentRequestMode

AgentResponse

Fields

AgentResult

AgentWorkspace

FileScanPolicy

ProjectScanner

FileReader

ModelProvider

ModelRequest

ModelResponse

ModelResponseStatus

OllamaProvider

Tool

ToolRegistry

ToolCall

ToolResult

FileReadTool

CommandTool

AgentRunStore

AgentRunTimer

AgentId

AgentFingerprint

Error names

Complete example

Next step