ADK-TSToolContext
Memory search, artifact listing, and flow control — everything a tool needs to interact with the agent's runtime.
ToolContext extends CallbackContext with capabilities specific to tool execution: searching long-term memory, listing session artifacts, and triggering flow control actions. ADK-TS injects it automatically into every tool call — you never construct it yourself.
import { ToolContext } from "@iqai/adk";For guidance on how to receive ToolContext in different tool styles (createTool, function tools, class-based tools), see ToolContext in Tools.
Added properties
functionCallId
The identifier the LLM assigned to this particular function call. ADK-TS generates one if the model didn't supply it. Use it when you need to correlate a tool response with the triggering call in logs or custom event processing.
functionCallId?: stringactions
A shorthand alias for eventActions. Use it to set flow control flags such as transferToAgent or escalate.
get actions(): EventActionssession
The current Session object, giving direct access to session.id, session.state, and session.events.
get session(): SessionsessionService
The BaseSessionService instance. Provides createSession, getSession, listSessions, deleteSession, and endSession.
get sessionService(): BaseSessionServicememoryService
The MemoryService instance, or undefined if no memory service was configured in the runner. Always guard against undefined before calling methods on it.
get memoryService(): MemoryService | undefinedMethods
listArtifacts()
Returns the filenames of every artifact currently saved in this session. Use it when your tool needs to discover what files are available before deciding which to load.
async listArtifacts(): Promise<string[]>import { createTool, ToolContext } from "@iqai/adk";
import { z } from "zod";
const listFilesTool = createTool({
name: "list_files",
description: "List all files available in the session",
schema: z.object({}),
fn: async (_args, ctx: ToolContext) => {
const files = await ctx.listArtifacts();
return { files, count: files.length };
},
});Throws if no artifact service is configured. Check that you've called
.withArtifactService(...) on the agent builder.
searchMemory()
Searches the long-term memory store for records relevant to the query. Returns an array of MemorySearchResult objects, each with a memory record and a numeric score (0–1, higher is better).
async searchMemory(query: string): Promise<MemorySearchResult[]>import { createTool, ToolContext } from "@iqai/adk";
import type { MemorySearchResult } from "@iqai/adk";
import { z } from "zod";
const recallTool = createTool({
name: "recall",
description: "Search the user's long-term memory",
schema: z.object({ query: z.string() }),
fn: async ({ query }, ctx: ToolContext) => {
const results: MemorySearchResult[] = await ctx.searchMemory(query);
return results.map(r => ({
score: r.score,
content: r.memory.content,
}));
},
});Throws if no memory service is configured. You can also check
ctx.memoryService before calling to avoid the throw in optional scenarios.
Flow control with actions
The actions property exposes the EventActions for this tool call. Setting flags on it signals the framework to change execution flow after the tool returns.
Transfer to another agent:
import { createTool, ToolContext } from "@iqai/adk";
import { z } from "zod";
const routeTool = createTool({
name: "route_to_billing",
description: "Transfer the conversation to the billing agent",
schema: z.object({}),
fn: (_args, ctx: ToolContext) => {
ctx.actions.transferToAgent = "billing_agent";
return { status: "transferring" };
},
});Escalate out of the current loop:
import { createTool, ToolContext } from "@iqai/adk";
import { z } from "zod";
const escalateTool = createTool({
name: "escalate",
description: "Escalate to a human agent",
schema: z.object({ reason: z.string() }),
fn: ({ reason }, ctx: ToolContext) => {
ctx.actions.escalate = true;
return { escalated: true, reason };
},
});Next steps
🔁 CallbackContext
The parent class — mutable state and artifact operations
⚙️ InvocationContext
Full service access for custom agent implementations
📝 ToolContext in Tools
How to receive ToolContext in createTool, function tools, and class-based tools
💡 Context Patterns
State scoping, anti-patterns, and testing strategies