neograph::llm::Agent Class Reference

Standalone ReAct agent that loops between LLM calls and tool execution. More...

#include <agent.h>

Public Member Functions
	Agent (std::shared_ptr< Provider > provider, std::vector< std::unique_ptr< Tool > > tools, const std::string &instructions="", const std::string &model="")
	Construct an agent with a provider and tools.
sp::runtime::Result	complete (const std::vector< sp::Message > &messages)
	Perform a single LLM completion (no tool loop).
sp::runtime::Result	run (std::vector< sp::Message > &messages, int max_iterations, ToolExecutionContext effect_context)
	Per-run host Tool broker context; caller supplies stable owner/run/thread and grant identity.
sp::runtime::Result	run (std::vector< sp::Message > &messages, int max_iterations=10)
	Run the agent loop until completion.
sp::runtime::Result	run_stream (std::vector< sp::Message > &messages, const std::function< void(const sp::Event &)> &on_event, int max_iterations=10)
	Run the agent loop with the explicit typed streaming mode.
void	set_hook_runtime (std::shared_ptr<::neograph::HookRuntime > runtime)
	Install the host-owned lifecycle boundary used by standalone tool dispatch.
void	set_runtime_interposition (std::shared_ptr<::neograph::RuntimeInterpositionController > controller)
	Opt into assembled, receipt-journaled provider dispatch for this agent.
void	set_tool_detection_timeout_seconds (int timeout_seconds)
	Override the initial streamed tool-detection turn's absolute deadline.
void	set_tool_execution_controller (std::shared_ptr< ToolExecutionController > controller)
	Inject a host-shared resource admission boundary for tool execution.
void	set_tool_gate (ToolGate gate)
	Intercept every tool call before it runs (issue #89).
sp::Usage	usage () const
	Token usage accumulated across every call this agent has made (#88).

Detailed Description

Standalone ReAct agent that loops between LLM calls and tool execution.

The agent sends messages to the LLM, checks for tool calls, executes them, feeds results back, and repeats until the LLM produces a final text response or the iteration limit is reached.

auto agent = Agent(provider, std::move(tools), "You are a helpful assistant.");
std::vector<sp::Message> messages = {{.role = sp::Role::User, .parts = {sp::Text{"What's 2+2?"}}}};
auto outcome = agent.run(messages);

See also

neograph::graph::create_react_graph for the graph-based equivalent.

Definition at line 39 of file agent.h.

Constructor & Destructor Documentation

Agent()

neograph::llm::Agent::Agent	(	std::shared_ptr< Provider >	provider,
		std::vector< std::unique_ptr< Tool > >	tools,
		const std::string &	instructions = "",
		const std::string &	model = ""
	)

Construct an agent with a provider and tools.

Parameters

provider	LLM provider for making completions.
tools	Vector of tools available to the agent (ownership transferred).
instructions	Optional system prompt prepended to the conversation.
model	Optional model name override (empty = use provider default).

Member Function Documentation

complete()

sp::runtime::Result neograph::llm::Agent::complete

(

const std::vector< sp::Message > &

messages

)

Perform a single LLM completion (no tool loop).

Parameters

messages

Conversation history (not modified).

Returns

The full completion response.

run() [1/2]

sp::runtime::Result neograph::llm::Agent::run	(	std::vector< sp::Message > &	messages,
		int	max_iterations,
		ToolExecutionContext	effect_context
	)

Per-run host Tool broker context; caller supplies stable owner/run/thread and grant identity.

An interrupted batch is replayed from messages on reconnect before another provider turn is requested.

run() [2/2]

sp::runtime::Result neograph::llm::Agent::run	(	std::vector< sp::Message > &	messages,
		int	max_iterations = 10
	)

Run the agent loop until completion.

Iterates between LLM calls and tool execution until the LLM produces a response with no tool calls, or max_iterations is reached.

Parameters

[in,out]	messages	Conversation history (modified in-place with new messages).
	max_iterations	Maximum number of LLM call iterations (default: 10).

Returns

The full immutable final provider outcome.

run_stream()

sp::runtime::Result neograph::llm::Agent::run_stream	(	std::vector< sp::Message > &	messages,
		const std::function< void(const sp::Event &)> &	on_event,
		int	max_iterations = 10
	)

Run the agent loop with the explicit typed streaming mode.

Every provider turn streams typed events exactly once; no response is discarded and re-requested merely to produce display text.

Parameters

[in,out]	messages	Full history, extended with every returned message.
	on_event	Callback receiving borrowed SDK event views.
	max_iterations	Maximum LLM call iterations.

Returns

The full immutable final provider outcome.

set_tool_detection_timeout_seconds()

void neograph::llm::Agent::set_tool_detection_timeout_seconds ( int  timeout_seconds )

inline

Override the initial streamed tool-detection turn's absolute deadline.

Positive values are seconds; -1 keeps the provider's default deadline.

Definition at line 145 of file agent.h.

set_tool_execution_controller()

void neograph::llm::Agent::set_tool_execution_controller ( std::shared_ptr< ToolExecutionController >  controller )

inline

Inject a host-shared resource admission boundary for tool execution.

Empty restores the conservative process-default controller.

Definition at line 138 of file agent.h.

set_tool_gate()

void neograph::llm::Agent::set_tool_gate ( ToolGate  gate )

inline

Intercept every tool call before it runs (issue #89).

The same gate the graph path takes from EngineConfig::tool_gate or GraphEngine::set_tool_gate. Both route through one dispatcher (issue #87), which is what stops a capability like this from landing in one path and silently missing the other — as concurrency once did.

An Interrupt verdict throws graph::NodeInterrupt out of run(): the Agent is standalone and has no checkpoint machinery to pause into. Callers wanting pause-and-resume want the graph path.

Definition at line 134 of file agent.h.

usage()

sp::Usage neograph::llm::Agent::usage ( ) const

inline

Token usage accumulated across every call this agent has made (#88).

The graph path reports usage through RunResult::usage. Agent is not a graph run and has no RunContext, so it keeps its own running total — otherwise token accounting would exist on one of the two ways to drive an LLM and not the other, which is precisely the split that #87 was about.

Cumulative over the agent's lifetime, not per run(): an agent loop makes several LLM calls per run and the interesting number is what the whole conversation cost.

Definition at line 118 of file agent.h.

---

The documentation for this class was generated from the following file:

• include/neograph/llm/agent.h