[Question] Best way of passing parameters between root LLM agent and sequential agent-as-a-tool

[amisev]

Hello ADK Team,

I'm looking for guidance on the best practice for passing initial parameters from a root LLMAgent to a SequentialAgent that is being used as a tool.

1. My Setup

My setup involves a root LLMAgent that uses AgentTool to delegate tasks to a multi-step SequentialAgent.

# A multi-step agent that will be used as a tool """
foo_tool_agent = SequentialAgent(
    name="FooTool",
    sub_agents=[...], # Contains one or more BaseAgents
    description="A tool that performs a multi-step task.",
)

# The root agent that calls the tool
bar_assistant_agent = Agent(
    name="BarAssistant",
    model="gemini-2.5-flash",
    tools=[AgentTool(agent=foo_tool_agent)],
)

2. Observed Data Flow

When the BarAssistant's LLM generates a tool call for my SequentialAgent, the function call looks like this:

"function_call": {
    "name": "FooTool",
    "args": { "request": "{\"param1\": \"valueA\", \"param2\": 123}" }
}

By inspecting the AgentTool's source code, I can see that it takes the string value from args['request'] and wraps it in a types.Content object. This Content object is then passed as the new_message to the Runner that executes the foo_tool_agent.

3. The Question: How to Read the Arguments?

My question is: What is the official or most idiomatic way for the first sub-agent inside FooTool to access this initial request string ("{"param1": "valueA", "param2": 123}")?

I see a few potential ways to access this data from the ctx object within my sub-agent's _run_async_impl method:

A) From ctx.user_content: Should I access the raw message directly?

request_str = ctx.user_content.parts[0].text
params = json.loads(request_str)

B) From the Session Events List: Should I parse the last event from the session history?

last_event = ctx.session.events[-1]
request_str = last_event.content.parts[0].text
params = json.loads(request_str)

I would appreciate any clarity on the recommended approach for this common agent-as-a-tool pattern. Thank you!

[hangfei]

@adk-bot

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

TLDR: The recommended approach is to use ctx.user_content to access the initial parameters passed to your SequentialAgent.

---

Hello @amisev,

Thank you for the detailed question. This is a great question about the idiomatic way to handle parameter passing in the "agent-as-a-tool" pattern.

Recommended Approach: Using ctx.user_content

The most direct and robust way for the first sub-agent inside your FooTool (SequentialAgent) to access the initial request is Option A from your question:

import json

# Inside your sub-agent's _run_async_impl method
request_str = ctx.user_content.parts[0].text
params = json.loads(request_str)

Why ctx.user_content is a good option?

When AgentTool executes your SequentialAgent, it initiates a new, nested invocation for that agent. The request string from the tool call is intentionally packaged as a types.Content object and becomes the user_content for that specific invocation. The user_content attribute is designed to hold the initial message that triggers an agent's run, making it the most reliable place to look for the input data. [1]

Regarding the Session Events List

While inspecting ctx.session.events (your Option B) might work, it's less ideal. The session history is a log of all events that have occurred, and relying on the last event (events[-1]) can be brittle. Future versions of the framework or the introduction of other interceptors could add intermediate events, which would break the logic of assuming the last event is always the one you're looking for.

In summary, ctx.user_content provides a stable and direct API for accessing the input of the current agent's execution context and is the recommended method for this use case.

[1] https://google.github.io/adk-docs/context/

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

TLDR: The recommended and most robust approach is option A: ctx.user_content. It directly and reliably provides the input that initiated your agent's current task.

---

Hello! That's an excellent question about a common and powerful pattern in ADK: using one agent as a tool for another.

Recommended Approach: ctx.user_content

The most idiomatic and reliable way for your sub-agent to access its initial input is by using ctx.user_content. [11]

# Inside the first sub-agent of your SequentialAgent
async def _run_async_impl(self, ctx: InvocationContext) -> ...:
    # Correct: Directly access the input for this invocation
    request_str = ctx.user_content.parts[0].text
    params = json.loads(request_str)
    ...

Why this is the best practice:

1. Semantic Clarity: ctx.user_content is specifically designed to hold the content that triggered the current invocation of the agent. [11] When AgentTool runs your SequentialAgent, it treats the request string from the tool call as the initial user content for that new execution context. This makes your code clearer and easier to understand.
2. Robustness: This approach is not dependent on the ordering or presence of other events in the session history. While ctx.session.events[-1] might work in a simple case, it is more fragile. Complex workflows or future ADK features could introduce intermediate events (e.g., for state changes or callbacks), which would cause logic based on the [-1] index to fail. [20]

A Note on Passing Data Between Sub-Agents

Once your SequentialAgent has started, the idiomatic way to pass data between its internal steps (e.g., from sub_agent_1 to sub_agent_2) is by using the shared session state (ctx.session.state).

You can do this by setting the output_key on your sub-agents, which automatically saves their result to the state for the next agent in the sequence to use. [1, 10]

For example:

# In the first sub-agent, you might parse the initial request and place it in the state
ctx.session.state['parsed_params'] = params

# Or, an LLMAgent can do this automatically
step1 = LlmAgent(
    name="ParseRequest",
    instruction="Parse the user request and extract param1.",
    output_key="extracted_param1" # Result is saved to ctx.session.state['extracted_param1']
)

step2 = LlmAgent(
    name="UseParameter",
    instruction="Perform an action using {extracted_param1}." # ADK injects the value from state
)

foo_tool_agent = SequentialAgent(sub_agents=[step1, step2])

This ensures a clean flow of data, where ctx.user_content is the entry point for the tool, and ctx.session.state is the medium for communication within the tool's internal workflow.

Hope this helps clarify the best practice!