google-adk-kotlin-core/com.google.adk.kt.tools/ToolContext

ToolContext

class ToolContext(invocationContext: InvocationContext, actions: EventActions = EventActions(), functionCallId: String? = null, toolConfirmation: ToolConfirmation? = null, eventId: String? = null) : Context

Context passed to tool executions.

This subclass is kept for backward compatibility. Prefer Context in new code.

A tool context is not a node activation, so the node-only members inherited from Context (such as Context.output and Context.routes) throw IllegalStateException here.

Constructors

ToolContext

constructor(invocationContext: InvocationContext, actions: EventActions = EventActions(), functionCallId: String? = null, toolConfirmation: ToolConfirmation? = null, eventId: String? = null)

Properties

actions

var actions: EventActions

The event actions for the current context, holding state deltas and control-flow signals to be attached to emitted events.

agent

val agent: BaseAgent

agentName

override val agentName: String

The name of the agent that is being invoked.

artifactService

override val artifactService: ArtifactService?

The ArtifactService instance.

attemptCount

@ExperimentalWorkflowApi

var attemptCount: Int

1-based attempt number, which a retry increments. 1 off-graph.

branch

override val branch: String?

The branch of the invocation context.

callbackContextData

val callbackContextData: MutableMap<String, Any>

Per-invocation scratch data; see ContextFrameworkData.callbackContextData.

context

override val context: ReadonlyContext

The readonly invocation context.

eventActions

val eventActions: EventActions

The same EventActions instance as actions, under the property name used by callbacks.

eventAuthor

@ExperimentalWorkflowApi

var eventAuthor: String

The author stamped on events this node emits.

eventId

override val eventId: String?

The unique ID of the event that triggered this tool call.

functionCallId

override val functionCallId: String?

The unique ID of the function call.

hasProducedOutput

@ExperimentalWorkflowApi

val hasProducedOutput: Boolean

Whether an output has been produced, by this node or by a useAsOutput delegate.

interruptIds

@ExperimentalWorkflowApi

val interruptIds: Set<String>

Interrupt IDs this node activation is waiting on.

invocationContext

val invocationContext: InvocationContext

invocationId

override val invocationId: String

The unique ID of this invocation.

memoryService

override val memoryService: MemoryService?

The MemoryService instance.

node

@ExperimentalWorkflowApi

val node: Node

The node this context is an activation of.

nodePath

@ExperimentalWorkflowApi

val nodePath: String

This activation's path: name@runId segments joined by /, rooted at the outermost node.

output

@ExperimentalWorkflowApi

var output: Any?

The node's output value, or null if none was produced. Unlike Python's public ctx.output setter, and like Go, node code cannot assign it: a node {} body outputs by returning a value, a custom node by emitting one or calling setOutput, and either can hand it to a child with runNode's useAsOutput.

parent

@ExperimentalWorkflowApi

var parent: Context?

The context of the node that scheduled this one, or null at the root or off-graph.

resumeInputs

@ExperimentalWorkflowApi

var resumeInputs: Map<String, Any?>

Answers to this node's interrupts, keyed by interrupt id. Empty off-graph.

routes

@ExperimentalWorkflowApi

var routes: List<Route>?

The routes this node selected, read by the scheduler to pick the outgoing edges.

runConfig

override val runConfig: RunConfig?

The run configuration for this invocation.

runId

@ExperimentalWorkflowApi

var runId: String

This activation's id within its node, counting from "1". It is a string because it forms the name@runId segment of a node path. "1" off-graph.

session

override val session: Session

The session that this invocation is a part of.

state

override val state: Map<String, Any>

The delta-aware state of the current session: committed session state merged with pending actions stateDelta writes, with removed keys filtered out.

toolConfirmation

var toolConfirmation: ToolConfirmation?

The user's answer to the current tool call's, or node run's, confirmation request.

userContent

override val userContent: Content?

The user content that this invocation is processing.

userId

override val userId: String

The user ID of the user that initiated the session.

Functions

addEventsToMemory

suspend fun addEventsToMemory(events: List<Event>, customMetadata: Map<String, Any?>? = null)

Adds an explicit list of events to the memory service, scoped to the current session's app/user/session ids.

addMemory

suspend fun addMemory(memories: List<MemoryEntry>, customMetadata: Map<String, Any?>? = null)

Adds explicit memories directly to the memory service, scoped to the current session's app/user ids.

addSessionToMemory

suspend fun addSessionToMemory()

Triggers memory generation for the current session.

endInvocation

fun endInvocation()

Requests the current LLM agent to stop after the current step completes.

getEvents

suspend override fun getEvents(currentInvocation: Boolean = false, currentBranch: Boolean = false): List<Event>

Returns the events from the current session.

listArtifacts

suspend override fun listArtifacts(): List<String>

Lists the filenames of the artifacts attached to the current session. Returns an empty list if no artifact service is configured.

loadArtifact

suspend override fun loadArtifact(name: String, version: Int? = null): Part?

Loads an artifact attached to the current session by name. Returns null if no artifact service is configured or the artifact is not found.

mergeEventActions

fun mergeEventActions(actions: EventActions)

Merges the given event actions into the current event actions, replacing actions with the merged result, after checking their state delta against the state schema in force here. Any reference to actions taken before the merge will not receive subsequent writes.

requestConfirmation

fun requestConfirmation(hint: String? = null, payload: Any? = null)

Requests confirmation for the current tool call. Only a tool call has a functionCallId, so this can only be called in a tool context.

runNode

@CanIgnoreReturnValue

@ExperimentalWorkflowApi

suspend fun runNode(node: Node, nodeInput: Any? = null, runId: String? = null, useAsOutput: Boolean = false, useSubBranch: Boolean = false, overrideBranch: String? = null, overrideIsolationScope: String? = null, raiseOnWait: Boolean = false): Any?

Executes node as a child of this node activation and returns its output. When node is an agent that hands off with transfer_to_agent, the handoffs are followed and the last agent's output is returned.

saveArtifact

suspend fun saveArtifact(name: String, artifact: Part): Int

Saves artifact under name in the current session, records the new version in actions' artifactDelta, and returns the saved version number.

setOutput

@ExperimentalWorkflowApi

inline fun <T : Any> setOutput(value: T)

Sets this node's output to value's JSON form under T's serializer, or to a Content as it is, so a successor typed T reads it back, live and after a session reload. Can be called at most once per activation, and drops value if runNode already delegated output to a child with useAsOutput. Use it from a custom node for a typed value, since emitting that value directly fails the node.

updateState

fun updateState(key: String, value: Any)

Records a state change in actions stateDelta (copy-on-write) so it appears in state and flushes on the next event. State.TEMP_PREFIX keys are never stored; keys without an app:, user: or temp: prefix must match the node's state schema, if any, and the checked value is stored.