Found docs updates needed from ADK python release v2.7.0 to v2.7.1
- Dominant language
- Shell
- Stars
- 1.5k
- Forks
- 1.3k
- Avg merge
- 7d 1h
- Merged PRs (30d)
- 34
Description
[Compare Link: v2.7.0...v2.7.1](https://github.com/google/adk-python/compare/v2.7.0...v2.7.1)
### 1. **Update the "Create a new session" cURL example to use the new non-deprecated endpoint and document the `events` parameter validation.**
**Doc file**: docs/runtime/api-server.md
**Current state**:
> **Create a new session**
>
> With the API server still running, open a new terminal window or tab and create
> a new session with the agent using:
>
> ```shell
> curl -X POST http://localhost:8000/apps/my_sample_agent/users/u_123/sessions/s_123 \
> -H "Content-Type: application/json" \
> -d '{"key1": "value1", "key2": 42}'
> ```
>
> Let's break down what's happening:
>
> * `http://localhost:8000/apps/my_sample_agent/users/u_123/sessions/s_123`: This
> creates a new session for your agent `my_sample_agent`, which is the name of
> the agent folder, for a user ID (`u_123`) and for a session ID (`s_123`). You
> can replace `my_sample_agent` with the name of your agent folder. You can
> replace `u_123` with a specific user ID, and `s_123` with a specific session
> ID.
> * `{"key1": "value1", "key2": 42}`: This is optional. You can use
> this to customize the agent's pre-existing state (dict) when creating the
> session.
**Proposed Change**:
> **Create a new session**
>
> With the API server still running, open a new terminal window or tab and create
> a new session with the agent using:
>
> ```shell
> curl -X POST http://localhost:8000/apps/my_sample_agent/users/u_123/sessions \
> -H "Content-Type: application/json" \
> -d '{"sessionId": "s_123", "state": {"key1": "value1", "key2": 42}}'
> ```
>
> Let's break down what's happening:
>
> * `http://localhost:8000/apps/my_sample_agent/users/u_123/sessions`: This
> creates a new session for your agent `my_sample_agent`, which is the name of
> the agent folder, for a user ID (`u_123`). You can replace `my_sample_agent`
> with the name of your agent folder and `u_123` with a specific user ID.
> * `{"sessionId": "s_123", "state": {"key1": "value1", "key2": 42}}`: This specifies
> the `sessionId` (optional; if omitted, a random UUID is generated) and the
> agent's pre-existing `state` (optional). You can also include an `events` array
> to initialize the session with a history. Note that any client-supplied events
> claiming to be ADK-generated (e.g., containing long-running tool IDs,
> non-default actions, or ADK reserved function calls) will be rejected with
> a 400 Bad Request error.
**Reasoning**:
The REST API example for session creation uses a deprecated endpoint (`POST /sessions/{session_id}`). It should be updated to use the active `POST /sessions` endpoint with the `CreateSessionRequest` JSON payload. Additionally, we need to document the new validation logic added to this endpoint, which rejects any initialization `events` passed by the client that claim to be ADK-generated (to prevent security/protocol spoofing).
**Reference**: src/google/adk/cli/api_server.py
Contributor guide
Research direction
Start with docs/runtime/api-server.md and compare its session-creation example with the referenced src/google/adk/cli/api_server.py entry point and the v2.7.0...v2.7.1 changes. Update the example to use POST /sessions, document the sessionId, state, and events behavior, and verify that the endpoint and 400 Bad Request validation description match the release.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, shell
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 84/100