agents::Context Class Reference

Context for an agent, containing tools, LLM, and memory. More...

#include <context.h>

Public Types
using	OnBeforeToolExecutionCallback = std::function<void(const std::string& tool_name, const JsonObject& params)>
	Callback type for before tool execution.
using	OnAfterToolExecutionCallback = std::function<void(const std::string& tool_name, const JsonObject& params, ToolResult& result)>
	Callback type for after tool execution.
using	OnBeforePromptAssemblyCallback = std::function<void(std::vector<Message>& messages)>
	Callback type for before prompt assembly.
using	OnBeforeCompactionCallback = std::function<void(std::vector<Message>& messages)>
	Callback type for before compaction.

Public Member Functions
	Context ()
	Default constructor for Context.
	Context (std::shared_ptr< LLMInterface > llm)
	Construct a new Context object with an llm.
	~Context ()=default
	Default destructor for Context.
void	setLLM (std::shared_ptr< LLMInterface > llm)
	Set the LLM to use.
std::shared_ptr< LLMInterface >	getLLM () const
	Get the LLM.
void	setSystemPrompt (const std::string &system_prompt)
	Set the system prompt.
const std::string &	getSystemPrompt () const
	Get the system prompt.
void	setTrustLevel (TrustLevel trust_level)
	Set the trust level.
TrustLevel	getTrustLevel () const
	Get the trust level.
void	loadWorkspaceConfig (const std::string &extra_dir="")
	Load the full workspace configuration in one call:
void	loadSkills (const std::vector< std::string > &directories={})
	Load Markdown skills and register them as tools. Skills with unmet requires.bins or requires.env are silently skipped.
void	setOnBeforeToolExecution (OnBeforeToolExecutionCallback callback)
	Set the onBeforeToolExecution callback.
void	setOnAfterToolExecution (OnAfterToolExecutionCallback callback)
	Set the onAfterToolExecution callback.
void	setOnBeforePromptAssembly (OnBeforePromptAssemblyCallback callback)
	Set the onBeforePromptAssembly callback.
void	setOnBeforeCompaction (OnBeforeCompactionCallback callback)
	Set the onBeforeCompaction callback.
void	setMaxConversationMessages (size_t max)
	Set the maximum conversation message count before compaction is triggered.
void	registerToolRegistry (tools::ToolRegistry &registry)
	Register tools from a ToolRegistry.
void	registerTool (std::shared_ptr< Tool > tool)
	Register a tool.
std::shared_ptr< Tool >	getTool (const std::string &name) const
	Get a tool by name.
std::vector< std::shared_ptr< Tool > >	getTools () const
	Get all tools.
void	removeTool (const std::string &name)
	Remove a tool from the catalog the agent sees.
Task< ToolResult >	executeTool (const std::string &name, const JsonObject &params, const std::string &tool_call_id="")
	Execute a tool by name using coroutines.
std::shared_ptr< Memory >	getMemory () const
	Get the memory.
void	addMessage (const Message &message)
	Add a message to the conversation history.
std::vector< Message >	getMessages () const
	Get all messages in the conversation history.
Task< LLMResponse >	chat (const std::string user_message, const std::vector< std::string > uris_or_data={})
	Multimodal chat completion with the current context.
Task< LLMResponse >	chatWithTools (const std::string user_message, const std::vector< std::string > uris_or_data={})
	Multimodal chat completion with tools.
AsyncGenerator< std::string >	streamChat (const std::string user_message, const std::vector< std::string > uris_or_data={})
	Multimodal streaming chat (accepts one or more media URIs or data strings).
AsyncGenerator< std::string >	streamChatWithTools (const std::string user_message, const std::vector< std::string > uris_or_data={})
	Multimodal streaming chat with tools.

Detailed Description

Context for an agent, containing tools, LLM, and memory.

Member Typedef Documentation

OnAfterToolExecutionCallback

using agents::Context::OnAfterToolExecutionCallback = std::function<void(const std::string& tool_name, const JsonObject& params, ToolResult& result)>

Callback type for after tool execution.

Note

Fired with the actual result so observers can react to outcomes

Constructor & Destructor Documentation

Context()

agents::Context::Context

(

std::shared_ptr< LLMInterface >

llm

)

Construct a new Context object with an llm.

Parameters

llm	The llm to use

Member Function Documentation

addMessage()

void agents::Context::addMessage

(

const Message &

message

)

Add a message to the conversation history.

Parameters

message

The message to add

chat()

Task< LLMResponse > agents::Context::chat	(	const std::string	user_message,
		const std::vector< std::string >	uris_or_data = {} )

Multimodal chat completion with the current context.

Parameters

user_message	The user message to send
uris_or_data	Optional URIs or data to use

Returns

The LLM response

chatWithTools()

Task< LLMResponse > agents::Context::chatWithTools	(	const std::string	user_message,
		const std::vector< std::string >	uris_or_data = {} )

Multimodal chat completion with tools.

Parameters

user_message	The user message to send
uris_or_data	Optional URIs or data to use

Returns

The LLM response

executeTool()

Task< ToolResult > agents::Context::executeTool	(	const std::string &	name,
		const JsonObject &	params,
		const std::string &	tool_call_id = "" )

Execute a tool by name using coroutines.

Parameters

name	The name of the tool to execute
params	The parameters to pass to the tool
tool_call_id	Optional tool call ID

Returns

The result of the tool execution

getLLM()

std::shared_ptr< LLMInterface > agents::Context::getLLM

(

)

const

Get the LLM.

Returns

The LLM

getMemory()

std::shared_ptr< Memory > agents::Context::getMemory

(

)

const

Get the memory.

Returns

The memory

getMessages()

std::vector< Message > agents::Context::getMessages

(

)

const

Get all messages in the conversation history.

Returns

The messages

getSystemPrompt()

const std::string & agents::Context::getSystemPrompt

(

)

const

Get the system prompt.

Returns

The system prompt

getTool()

std::shared_ptr< Tool > agents::Context::getTool

(

const std::string &

name

)

const

Get a tool by name.

Parameters

name	The name of the tool to get

Returns

Pointer to tool

getTools()

std::vector< std::shared_ptr< Tool > > agents::Context::getTools

(

)

const

Get all tools.

Returns

The tools

getTrustLevel()

TrustLevel agents::Context::getTrustLevel

(

)

const

Get the trust level.

Returns

The trust level

loadSkills()

void agents::Context::loadSkills

(

const std::vector< std::string > &

directories = {}

)

Load Markdown skills and register them as tools. Skills with unmet requires.bins or requires.env are silently skipped.

Parameters

directories

Directories to search for .md skill files. Uses ~/.agents/skills, ~/.claude/skills, <cwd>/.agents/skills if empty.

loadWorkspaceConfig()

void agents::Context::loadWorkspaceConfig

(

const std::string &

extra_dir = ""

)

Load the full workspace configuration in one call:

1. Reads AGENTS.md, SOUL.md, USER.md, MEMORY.md, etc. into the system prompt.
2. Loads MCP server definitions from mcp.json.
3. Discovers and registers Markdown skills from <dir>/skills/.

Search order: extra_dir → .agents/ → .claude/

Parameters

extra_dir

Optional directory scanned first (e.g. "demos/in-car/.agents"). Useful for demo- or app-specific personas and skills that sit alongside the global workspace defaults.

registerTool()

void agents::Context::registerTool

(

std::shared_ptr< Tool >

tool

)

Register a tool.

Parameters

tool	The tool to register

registerToolRegistry()

void agents::Context::registerToolRegistry

(

tools::ToolRegistry &

registry

)

Register tools from a ToolRegistry.

Parameters

registry

The ToolRegistry to register from

removeTool()

void agents::Context::removeTool

(

const std::string &

name

)

Remove a tool from the catalog the agent sees.

Parameters

name	The name of the tool to remove

Note

Callers holding a shared_ptr to the tool (obtained via getTool) can still invoke it directly; this only removes it from the catalog advertised to the model.

setLLM()

void agents::Context::setLLM

(

std::shared_ptr< LLMInterface >

llm

)

Set the LLM to use.

Parameters

llm	The LLM to use

setMaxConversationMessages()

void agents::Context::setMaxConversationMessages

(

size_t

max

)

Set the maximum conversation message count before compaction is triggered.

Parameters

max	Number of messages (default: 40)

setOnAfterToolExecution()

void agents::Context::setOnAfterToolExecution

(

OnAfterToolExecutionCallback

callback

)

Set the onAfterToolExecution callback.

Parameters

callback

The callback to execute after a tool returns

setOnBeforeCompaction()

void agents::Context::setOnBeforeCompaction

(

OnBeforeCompactionCallback

callback

)

Set the onBeforeCompaction callback.

Parameters

callback

The callback to execute

setOnBeforePromptAssembly()

void agents::Context::setOnBeforePromptAssembly

(

OnBeforePromptAssemblyCallback

callback

)

Set the onBeforePromptAssembly callback.

Parameters

callback

The callback to execute

setOnBeforeToolExecution()

void agents::Context::setOnBeforeToolExecution

(

OnBeforeToolExecutionCallback

callback

)

Set the onBeforeToolExecution callback.

Parameters

callback

The callback to execute

setSystemPrompt()

void agents::Context::setSystemPrompt

(

const std::string &

system_prompt

)

Set the system prompt.

Parameters

system_prompt

The system prompt to use

setTrustLevel()

void agents::Context::setTrustLevel

(

TrustLevel

trust_level

)

Set the trust level.

Parameters

trust_level

The trust level

streamChat()

AsyncGenerator< std::string > agents::Context::streamChat	(	const std::string	user_message,
		const std::vector< std::string >	uris_or_data = {} )

Multimodal streaming chat (accepts one or more media URIs or data strings).

Parameters

user_message	The user message to send
uris_or_data	Optional URIs or data to use

Returns

The LLM response

streamChatWithTools()

AsyncGenerator< std::string > agents::Context::streamChatWithTools	(	const std::string	user_message,
		const std::vector< std::string >	uris_or_data = {} )

Multimodal streaming chat with tools.

Parameters

user_message	The user message to send
uris_or_data	Optional URIs or data to use

Returns

The LLM response