plexus.cli.procedure.lua_dsl.primitives.agent module

Agent Primitive - LLM agent operations.

Provides: - Agent.turn() - Execute one agent turn (reasoning + tool calls) - Agent.turn({inject = “message”}) - Inject additional context

class plexus.cli.procedure.lua_dsl.primitives.agent.AgentPrimitive(name: str, system_prompt: str, initial_message: str, llm, available_tools: List[Any], tool_primitive, stop_primitive, iterations_primitive, chat_recorder=None)

Bases: object

Executes LLM agent turns with tool calling.

Each agent has: - System prompt (instructions) - Initial message (kickoff) - Conversation history - Available tools - LLM instance

Initialize an agent primitive.

Args:

name: Agent name (e.g., “worker”, “assistant”) system_prompt: System prompt for the agent initial_message: Initial user message to kickoff llm: LangChain LLM instance with tools bound available_tools: List of available tool objects tool_primitive: ToolPrimitive instance for recording calls stop_primitive: StopPrimitive instance for stop detection iterations_primitive: IterationsPrimitive for tracking turns chat_recorder: Optional ProcedureChatRecorder for logging conversations

__init__(name: str, system_prompt: str, initial_message: str, llm, available_tools: List[Any], tool_primitive, stop_primitive, iterations_primitive, chat_recorder=None)

Initialize an agent primitive.

Args:

name: Agent name (e.g., “worker”, “assistant”) system_prompt: System prompt for the agent initial_message: Initial user message to kickoff llm: LangChain LLM instance with tools bound available_tools: List of available tool objects tool_primitive: ToolPrimitive instance for recording calls stop_primitive: StopPrimitive instance for stop detection iterations_primitive: IterationsPrimitive for tracking turns chat_recorder: Optional ProcedureChatRecorder for logging conversations

async flush_recordings()

Flush queued recordings to chat session (called by runtime after workflow).

get_conversation() → List[Any]

Get the current conversation history.

reset()

Reset the agent (mainly for testing).

turn(options: Dict[str, Any] | None = None) → Dict[str, Any]

Execute one agent turn.

Args:

options: Optional dict with:

• inject: Additional context message to inject for this turn

Returns:

Dictionary with response information (for Lua access)

Example (Lua):

local response = Worker.turn() Log.info(“Agent said: “ .. response.content)

for i, call in ipairs(response.tool_calls) do

Log.info(“Called tool: “ .. call.name)

end

class plexus.cli.procedure.lua_dsl.primitives.agent.AgentResponse(content: str, tool_calls: List[Dict[str, Any]], token_usage: Dict[str, int] | None = None)

Bases: object

Represents the response from an agent turn.

__init__(content: str, tool_calls: List[Dict[str, Any]], token_usage: Dict[str, int] | None = None)

to_dict() → Dict[str, Any]

Convert to dictionary for Lua access.