agent.h

Go to the documentation of this file.

 
#pragma once
 
#include <neograph/api.h>
#include <neograph/provider.h>
#include <neograph/tool.h>
#include <neograph/tool_dispatch.h>   // ToolGate (issue #89)
#include <functional>
#include <memory>
#include <string>
#include <vector>
 
namespace neograph { class RuntimeInterpositionController; }
namespace neograph { class HookRuntime; }
namespace neograph::llm {
 
class NEOGRAPH_API Agent {
  public:
    Agent(std::shared_ptr<Provider> provider,
          std::vector<std::unique_ptr<Tool>> tools,
          const std::string& instructions = "",
          const std::string& model = "");
 
    // Move-only — `tools_` is `vector<unique_ptr<Tool>>`. Explicit
    // declarations are required because Agent is NEOGRAPH_API and MSVC
    // eagerly instantiates all special members for dll-exported classes
    // (the implicit copy-assign tries to copy the vector → deleted →
    // C2280). GCC/Clang only instantiate on use, so the bug was Windows-
    // only and silently broke the wheel build.
    Agent(const Agent&)                     = delete;
    Agent& operator=(const Agent&)          = delete;
    Agent(Agent&&) noexcept                 = default;
    Agent& operator=(Agent&&) noexcept      = default;
    ~Agent()                                = default;
 
    sp::runtime::Result run(std::vector<sp::Message>& messages,
                    int max_iterations = 10);
    sp::runtime::Result run(std::vector<sp::Message>& messages, int max_iterations,
                    ToolExecutionContext effect_context);
 
    sp::runtime::Result run_stream(std::vector<sp::Message>& messages,
                           const std::function<void(const sp::Event&)>& on_event,
                           int max_iterations = 10);
    sp::runtime::Result run_stream(std::vector<sp::Message>& messages,
                           const std::function<void(const sp::Event&)>& on_event, int max_iterations,
                           ToolExecutionContext effect_context);
 
    sp::runtime::Result complete(const std::vector<sp::Message>& messages);
 
    sp::Usage usage() const { return usage_->snapshot(); }
    const std::vector<sp::runtime::Result>& outcomes() const noexcept { return outcomes_; }
 
    void set_tool_gate(ToolGate gate) { tool_gate_ = std::move(gate); }
 
    void set_tool_execution_controller(
        std::shared_ptr<ToolExecutionController> controller) {
        tool_execution_controller_ = std::move(controller);
    }
 
    void set_tool_detection_timeout_seconds(int timeout_seconds) {
        tool_detection_timeout_seconds_ = timeout_seconds;
    }
 
    void set_runtime_interposition(std::shared_ptr<::neograph::RuntimeInterpositionController> controller);
 
    void set_hook_runtime(std::shared_ptr<::neograph::HookRuntime> runtime) {
        hook_runtime_ = std::move(runtime);
    }
 
  private:
    std::shared_ptr<Provider> provider_;
    std::vector<std::unique_ptr<Tool>> tools_;
    std::string instructions_;
    std::string model_;
 
    std::shared_ptr<UsageAccumulator> usage_ = std::make_shared<UsageAccumulator>();
    std::vector<sp::runtime::Result> outcomes_;
 
    ToolGate tool_gate_;
 
    std::shared_ptr<ToolExecutionController> tool_execution_controller_;
 
    int tool_detection_timeout_seconds_ = -1;
    std::shared_ptr<::neograph::RuntimeInterpositionController> runtime_interposition_;
    std::shared_ptr<::neograph::HookRuntime> hook_runtime_;
 
    void ensure_system_message(std::vector<sp::Message>& messages);
    sp::runtime::Result run_loop(std::vector<sp::Message>& messages, int max_iterations,
                         ToolExecutionContext execution, ProviderMode mode,
                         std::function<void(const sp::Event&)> on_event);
    std::vector<ChatTool> get_tool_definitions() const;
 
    std::vector<Tool*> tool_ptrs() const;
};
 
} // namespace neograph::llm