runner.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (c) 2026 ForestHub. All rights reserved.
// For commercial licensing, visit https://github.com/ForestHubAI/fh-sdk
 
#ifndef FORESTHUB_AGENT_RUNNER_HPP
#define FORESTHUB_AGENT_RUNNER_HPP

 
#include <memory>
#include <string>
#include <vector>
 
#include "foresthub/agent/agent.hpp"
#include "foresthub/core/input.hpp"
#include "foresthub/core/provider.hpp"
#include "foresthub/util/json.hpp"
#include "foresthub/util/optional.hpp"
 
namespace foresthub {
namespace agent {
 
using json = nlohmann::json;

struct RunResult {
    json final_output;                  
    std::shared_ptr<Agent> last_agent;  
    int turns = 0;                      
};

struct RunResultOrError {
    foresthub::Optional<RunResult> result;  
    std::string error;                      

    bool HasError() const { return !error.empty(); }

    static RunResultOrError Success(RunResult result) { return {std::move(result), ""}; }

    static RunResultOrError Failure(std::string error_message) {
        return {foresthub::Optional<RunResult>{}, std::move(error_message)};
    }
};

class Runner {
public:
    Runner(std::shared_ptr<foresthub::core::LLMClient> client, foresthub::core::ModelID model);

    Runner& WithMaxTurns(int max_turns);

    RunResultOrError Run(const std::shared_ptr<Agent>& starting_agent, const std::shared_ptr<core::Input>& input);

    const std::shared_ptr<foresthub::core::LLMClient>& client() const { return client_; }
    const core::ModelID& default_model() const { return default_model_; }
    const foresthub::Optional<int>& max_turns() const { return max_turns_; }
 
private:
    std::shared_ptr<foresthub::core::LLMClient> client_;  
    core::ModelID default_model_;                         
    foresthub::Optional<int> max_turns_;                  

    struct ExecResult {
        std::shared_ptr<foresthub::core::Tool> handoff_tool;  
        foresthub::core::InputItems new_items;                
        bool is_handoff = false;                              
        std::string error;                                    
    };

    ExecResult ExecuteFunctionTools(const std::vector<foresthub::core::ToolCallRequest>& requests,
                                    const std::shared_ptr<Agent>& agent);
};
 
}  // namespace agent
}  // namespace foresthub
 
#endif  // FORESTHUB_AGENT_RUNNER_HPP