AgentCore

Category: Agent

Source: agent_core.dart

Classes

AgentCore

The agent core manages the LLM ↔ tool execution loop.

It runs independently from the UI, emitting [AgentEvent]s that the application subscribes to. The agentic loop:

1. Send messages to the LLM.
2. Stream back text and/or tool calls.
3. If tool calls are present: wait for execution results, add them to the conversation, and go to step 1.
4. If no tool calls: done.

Constructor

AgentCore({
    required this.llm,
    required this.tools,
    String? modelId,
    this._obs,
    this._traceParent,
  })

Properties

Property	Type	Description
llm	LlmClient
tools	Map<String, Tool>
modelId	String
stats	UsageStats	Cumulative usage across every LLM call this core has run. Surfaces (CLI status bar, ACP session/usage_summary, tests) read it directly via [stats]. The old tokenCount field has been removed — it counted only input + output and undercounted heavy-cache sessions, which the status bar then displayed in conflict with /usage. Use stats.totalTokens for the all-buckets total or stats.billedInputTokens to compute hit rate.
conversation	List<Message> get	The full conversation history.
allowedTools	List<Tool> get	Tools to send to the LLM, filtered by [toolFilter] when set.
conversation	List<Message> get	The full conversation history.

Methods

bool Function(Tool)

Optional predicate to exclude tools before sending to the LLM.

void setStartupNotice(String message, {String kind = 'info'})

Queue a one-shot [AgentNotice] to fire at the top of the next [run]. Overwrites any previously-queued startup notice — we only surface one per session boot to keep the transcript tidy.

void addMessage(Message message)

Adds a message directly to the conversation history.

void clearConversation()

Clear all conversation history (for session fork).

`Stream<AgentEvent> run(

String userMessage, {
List<ContentPart>? userContentParts,

})`

Runs a [userMessage] through the agent loop.

Returns a stream of [AgentEvent]s that the UI subscribes to. Pass [userContentParts] for multimodal input (images, resource links) — the LLM mappers will serialise them per provider.

void completeToolCall(ToolResult result)

Provides a [result] for a pending tool call.

Called by the application after the user approves (or denies) a tool invocation.

void ensureToolResultsComplete()

Ensures the conversation history is structurally valid for the next API call.

When the user cancels (Escape) while a tool is executing, the agent's stream subscription is cancelled. This kills the generator before it reaches the code that adds tool_result messages to the conversation. The conversation is left with an assistant message containing tool_use blocks but no matching tool_result messages — which the Anthropic and OpenAI APIs reject as invalid.

This method scans backwards from the end of the conversation, finds any unmatched tool_use blocks, and injects synthetic [cancelled] tool_result messages so the next API call succeeds.

Future<ToolResult> executeTool(ToolCall call)

Executes a [call] directly using the registered tool.