pi-agent-core — Agent Runtime

The Agent class wraps agentLoop with state management, event dispatch, steering/follow-up queues, and abort control. Use Agent for apps; use raw agentLoop only when you need direct async-iterator control without the barrier semantics.

Mental Model

Agent (state + queues + events)
  └── agentLoop (double loop: outer=follow-ups, inner=tool-calls+steering)
        └── streamAssistantResponse → transformContext → convertToLlm → streamFn → LLM
        └── executeToolCalls → prepare → execute → finalize

Key concepts:

• AgentMessage is the superset type (LLM messages + custom app messages)
• convertToLlm filters AgentMessage[] → Message[] at the LLM boundary
• transformContext optionally prunes/injects messages before conversion
• The Agent class provides a barrier — message_end commits the assistant message to state before tool preflight begins. Raw agentLoop streams are observational (no barrier).