Commit fc94e604 authored by Lluis Gifre Renom's avatar Lluis Gifre Renom
Browse files

Document Agentic ADK Web ingress behavior

parent 89f1d5de

src/agentic/README.md

+33 −15
Original line number Diff line number Diff line
@@ -39,7 +39,9 @@ The deployment manifest creates: 
- `agenticservice`: HTTP service exposing Google ADK Web and ADK A2A on

  port `8000`.

- `tfs-ingress-agentic`: ingress path `/agentic` for Google ADK Web, ADK

  API documentation, and ADK A2A endpoints.

  API documentation, and ADK A2A endpoints. The ingress preserves the

  `/agentic` prefix; it must not rewrite the path away because the ADK

  application is started with the same external root path.



When WebUI and Agentic are both selected in `TFS_COMPONENTS`, the TFS WebUI

navigation bar exposes an `Agentic` entry. The link opens Google ADK Web
@@ -155,6 +157,12 @@ The generated ADK API documentation is available as a debug endpoint: 
http://<controller-host>/agentic/docs

```



The Swagger page loads its OpenAPI definition from the prefixed endpoint:



```text

http://<controller-host>/agentic/openapi.json

```



The app-specific A2A Agent Card is exposed at:



```text
@@ -178,9 +186,15 @@ serves operator interaction and app-scoped A2A requests, which avoids split 
runner state and SQLite session collisions.



The package exposes `agentic.agent:root_agent` so ADK Web can discover the

same root agent used by the service. From a development checkout with the

Agentic dependencies installed, start ADK Web from the directory containing the

`agentic` package:

same root agent used by the service. The component launcher builds the ADK Web

FastAPI application programmatically, enables ADK A2A support, sets

`url_prefix` and FastAPI `root_path` to `ADK_HTTP_ROOT_PATH`, and runs Uvicorn

on port `8000`. This ensures that Swagger, ADK Web redirects, static assets,

and A2A routes all use the same external `/agentic` prefix when the component

is exposed behind the TFS ingress.



From a development checkout with the Agentic dependencies installed, start ADK

Web from the directory containing the `agentic` package:



```bash

cd ~/tfs-ctrl/src
@@ -189,17 +203,9 @@ cp agentic/agent.py /tmp/tfs-agentic-adk-apps/agentic/agent.py 
PYTHONPATH=. ADK_MODEL=dummy-deterministic python -m agentic.service.adk_web

```



The launcher writes the runtime Agent Card and executes:



```bash

adk web \

  --a2a \

  --host 0.0.0.0 \

  --port 8000 \

  --url_prefix /agentic \

  --session_service_uri sqlite:///<configured-session-db> \

  /tmp/tfs-agentic-adk-apps

```

The launcher writes the runtime Agent Card under the ADK app directory, builds

the ADK Web application with `web=True` and `a2a=True`, and uses

`ADK_SESSION_DB_PATH` for SQLite-backed ADK session persistence.



Then open:
@@ -221,6 +227,18 @@ kubectl -n tfs port-forward deployment/agenticservice 8000:8000 


Then open `http://127.0.0.1:8000/agentic`.



Useful route checks are:



```bash

curl http://<controller-host>/agentic/list-apps

curl http://<controller-host>/agentic/docs

curl http://<controller-host>/agentic/openapi.json

curl http://<controller-host>/agentic/a2a/agentic/.well-known/agent-card.json

```



The Kubernetes readiness and liveness probes use `/agentic/dev-ui/`, matching

the prefixed ADK Web route.



Structured peer A2A requests use a compact JSON action envelope. The root agent

detects this envelope before any LLM call and dispatches it to deterministic

domain actions, while normal operator prompts continue through the configured