Improve documentation related to managing state

[slilichenko]

State is discussed in this section: https://google.github.io/adk-docs/sessions/#core-concepts and in /sessions/state. https://google.github.io/adk-docs/sessions/state/#how-state-is-updated-recommended-methods indicates 3 recommended ways to update the state, but misses a quite important way to do through a context: https://google.github.io/adk-docs/context/#managing-session-state.

It takes some time to realize that when using a Context it's OK to do direct state manipulation, while session.state shouldn't be updated. Perhaps highlighting these distinctions will help avoid confusion.

[Pipasgonzalez]

@slilichenko I am still having a lot of trouble with this. How can I set/modify the state in one tool call which can then be used by another tool call later-on?
I have tried doing it like this:

async def search_internet_for_tools(ctx: ToolContext, search_query: str):
    try:
        # ... API fetches etc.

        ctx.state["temp:markdown_documents_pages"] = markdown_documents_pages
        ctx.state["temp:markdown_documents_full"] = markdown_documents_full
        ctx.state["temp:current_documents_filenames"] = file_names

        return {
            "status": "success",
            "message": f"Successfully found, downloaded and parsed {len(file_names)} documents",
        }

    except Exception as e:
        return {
            "status": "error",
            "message": f"Error while searching / downloading files: {str(e)}",
        }

The documents are to be used in a later tool call:

async def glimpse_documents(ctx: ToolContext) -> str:
    num_pages = 5
    markdown_pages = ctx.state["markdown_documents_pages"]
    filenames = ctx.state["current_documents_filenames"]

    #... rest of tool call
    return "\n".join(markdown_output)

But as soon as I run it I get."ValueError: Failed to parse the parameter ctx: google.adk.tools.tool_context.ToolContext of function search_internet_for_tools for automatic function calling. Automatic function calling works best with simpler function signature schema, consider manually parsing your function declaration for function search_internet_for_tools."

[slilichenko]

Rename the "ctx" parameter to be "tool_context" parameter and it should work.

[slilichenko]

Added this feature request to help prevent these errors.

[Sita04]

@slilichenko Modifying the documentation to address this issue.

Thank you very much for taking the time to report both the issue and the new feature request!