thanh-kit 2.5.0 → 2.5.2

package/templates/skills/google-adk-python/references/agent-types-and-architecture.md

@@ -0,0 +1,128 @@
+# Agent Types and Architecture
+
+## LlmAgent
+
+Dynamic routing agent.
+
+**Properties:** `model`, `instruction`, `description`, `tools`, `sub_agents`, `generate_content_config`
+
+```python
+from google.adk.agents import Agent
+
+agent = Agent(
+    name="assistant", model="gemini-2.5-flash",
+    instruction="You are a helpful assistant.",
+    tools=[search_tool], sub_agents=[code_agent],
+    generate_content_config={"temperature": 0.7}
+)
+```
+
+## Workflow Agents
+
+### SequentialAgent
+
+```python
+from google.adk.agents import SequentialAgent
+
+pipeline = SequentialAgent(
+    name="research_pipeline",
+    sub_agents=[
+        Agent(name="searcher", model="gemini-2.5-flash", tools=[search]),
+        Agent(name="writer", model="gemini-2.5-flash", tools=[write]),
+    ]
+)
+```
+
+### ParallelAgent
+
+```python
+from google.adk.agents import ParallelAgent
+
+parallel = ParallelAgent(
+    name="multi_source",
+    sub_agents=[
+        Agent(name="web", model="gemini-2.5-flash", tools=[web_search]),
+        Agent(name="db", model="gemini-2.5-flash", tools=[db_query]),
+    ]
+)
+```
+
+### LoopAgent
+
+```python
+from google.adk.agents import LoopAgent
+
+loop = LoopAgent(
+    name="refiner",
+    sub_agents=[
+        Agent(name="generator", model="gemini-2.5-flash", tools=[generate]),
+        Agent(name="validator", model="gemini-2.5-flash", tools=[validate]),
+    ],
+    max_iterations=5,
+)
+```
+
+## BaseAgent
+
+Override `run_async()` and `get_agent_card()`.
+
+```python
+from google.adk.agents.base_agent import BaseAgent
+
+class CustomAgent(BaseAgent):
+    async def run_async(self, query: str, context: dict) -> dict:
+        return {"response": "Custom"}
+```
+
+## Agent Structure
+
+```
+my_agent/
+├── __init__.py      # Export root_agent or app
+├── agent.py         # Agent definition
+└── tools.py         # Custom tools
+```
+
+```python
+# __init__.py
+from my_agent.agent import root_agent
+__all__ = ["root_agent"]
+
+# agent.py
+from google.adk.agents import Agent
+root_agent = Agent(name="my_agent", model="gemini-2.5-flash", instruction="...")
+
+# A2A server
+from google.adk.servers.a2a_server import create_a2a_server
+app = create_a2a_server(root_agent)
+```
+
+## Source Structure
+
+```
+src/google/adk/
+├── agents/                # Agent implementations
+├── tools/                 # Tool system
+├── sessions/              # Session management
+├── runners/               # Execution orchestration
+└── servers/               # A2A server utilities
+```
+
+## Global Instructions
+
+```python
+root = Agent(
+    name="root", model="gemini-2.5-flash",
+    instruction="Root behavior.",
+    global_instruction="Always be polite and concise.",
+    sub_agents=[Agent(name="sub1", model="gemini-2.5-flash")]
+)
+```
+
+## Best Practices
+
+- Use descriptive `name`/`description` for routing
+- Keep `instruction` focused on single responsibility
+- Delegate specialized tasks to sub-agents
+- Use workflow agents for orchestration
+- Export `root_agent` or `app` from `__init__.py`

package/templates/skills/google-adk-python/references/callbacks-plugins-observability.md

@@ -0,0 +1,117 @@
+# Callbacks, Plugins, Observability
+
+## Callback Types
+
+- `before_agent`, `after_agent`: Agent lifecycle
+- `before_model`, `after_model`: LLM calls
+- `before_tool`, `after_tool`: Tool execution
+
+## Callback Signatures
+
+```python
+from google.adk.agents.callback_context import CallbackContext
+from google.adk.models.content import ModelContent
+from google.adk.models.llm_request import LlmRequest
+from google.adk.models.llm_response import LlmResponse
+from google.adk.tools.tool_context import ToolContext
+
+def before_agent_callback(callback_context: CallbackContext) -> None:
+    print(f"Agent: {callback_context.agent_name}")
+
+def after_agent_callback(callback_context: CallbackContext) -> ModelContent | None:
+    return None
+
+def before_model_callback(callback_context: CallbackContext, llm_request: LlmRequest) -> None:
+    print(f"Model: {llm_request.model_id}")
+
+def after_model_callback(callback_context: CallbackContext, llm_response: LlmResponse) -> None:
+    print(f"Tokens: {llm_response.usage_metadata}")
+
+def before_tool_callback(tool: str, args: dict, tool_context: ToolContext) -> None:
+    print(f"Tool: {tool}")
+
+def after_tool_callback(tool: str, args: dict, tool_context: ToolContext, response: Any) -> Any:
+    return response
+```
+
+## Using Callbacks
+
+```python
+from google.adk.agents.web_agent import WebAgent
+
+agent = WebAgent(
+    name='my_agent', model='gemini-2.5-flash',
+    before_agent_callback=before_agent_callback,
+    before_model_callback=[callback1, callback2]
+)
+
+# Async supported
+async def async_callback(callback_context: CallbackContext) -> None:
+    await log_to_database(callback_context)
+```
+
+## Plugins
+
+```python
+from google.adk.plugins.base_plugin import BasePlugin
+from google.adk.agents.callback_context import CallbackContext
+from google.adk.models.llm_request import LlmRequest
+
+class CountPlugin(BasePlugin):
+    def __init__(self):
+        super().__init__(name='count')
+        self.count = 0
+
+    async def before_agent_callback(self, *, agent, callback_context: CallbackContext):
+        self.count += 1
+        print(f"#{self.count}")
+
+    async def before_model_callback(self, *, callback_context: CallbackContext, llm_request: LlmRequest):
+        print(f"Model: {llm_request.model_id}")
+
+agent = WebAgent(name='agent', model='gemini-2.5-flash', plugins=[CountPlugin()])
+```
+
+## Built-in Plugins
+
+```python
+from google.adk.plugins.save_files_as_artifacts_plugin import SaveFilesAsArtifactsPlugin
+from google.adk.plugins.context_filter_plugin import ContextFilterPlugin
+
+plugin1 = SaveFilesAsArtifactsPlugin()
+plugin2 = ContextFilterPlugin(filter_fn=lambda ctx: ctx.priority > 5)
+agent = WebAgent(name='agent', model='gemini-2.5-flash', plugins=[plugin1, plugin2])
+```
+
+## Observability
+
+### Arize Phoenix
+
+```python
+from phoenix.otel import register
+
+tracer_provider = register(
+    project_name='my_project',
+    endpoint='http://localhost:6006/v1/traces'
+)
+
+agent = WebAgent(name='agent', model='gemini-2.5-flash')
+result = await agent.run('What is 2+2?')
+```
+
+### Custom Metrics
+
+```python
+class MetricsPlugin(BasePlugin):
+    def __init__(self):
+        super().__init__(name='metrics')
+        self.latencies = []
+
+    async def before_model_callback(self, *, callback_context, llm_request):
+        callback_context.start_time = time.time()
+
+    async def after_model_callback(self, *, callback_context, llm_response):
+        latency = time.time() - callback_context.start_time
+        self.latencies.append(latency)
+        print(f"Avg: {sum(self.latencies) / len(self.latencies):.2f}s")
+```

package/templates/skills/google-adk-python/references/deployment-cloud-run-vertex-gke.md

@@ -0,0 +1,138 @@
+# Deployment: Cloud Run, Vertex AI, GKE
+
+## Development Modes
+
+```bash
+adk web samples/agents/my_agent.py:agent --port 8080
+adk run samples/agents/my_agent.py:agent "What is 2+2?" --streaming
+adk api_server samples/agents/my_agent.py:agent --port 8000
+```
+
+Endpoints: `/chat`, `/stream`, `/health`
+
+## Cloud Run
+
+```dockerfile
+FROM python:3.11-slim
+WORKDIR /app
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+COPY pyproject.toml uv.lock ./
+COPY src/ ./src/
+RUN uv sync --frozen --no-cache
+EXPOSE 8080
+CMD ["uv", "run", "adk", "api_server", "src/my_agent.py:agent", "--host", "0.0.0.0", "--port", "8080"]
+```
+
+```bash
+export PROJECT_ID=my-project REGION=us-central1
+gcloud builds submit --tag gcr.io/$PROJECT_ID/my-agent
+gcloud run deploy my-agent \
+  --image gcr.io/$PROJECT_ID/my-agent \
+  --region $REGION \
+  --set-env-vars GOOGLE_API_KEY=$GOOGLE_API_KEY
+
+# Secret Manager
+echo -n "key" | gcloud secrets create google-api-key --data-file=-
+gcloud run deploy my-agent --set-secrets GOOGLE_API_KEY=google-api-key:latest
+```
+
+## Vertex AI
+
+```bash
+adk deploy --target vertex --agent my_agent.py:agent --project my-project
+```
+
+```yaml
+agent:
+  name: my-agent
+  model: gemini-2.5-flash
+  region: us-central1
+  scaling: {min_instances: 1, max_instances: 10}
+  resources: {cpu: 2, memory: 4Gi}
+```
+
+```python
+from google.cloud import aiplatform
+aiplatform.init(project='my-project', location='us-central1')
+endpoint = aiplatform.Endpoint('projects/123/locations/us-central1/endpoints/456')
+response = endpoint.predict(instances=[{'prompt': 'What is 2+2?'}])
+```
+
+## GKE
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata: {name: my-agent}
+spec:
+  replicas: 3
+  template:
+    spec:
+      containers:
+      - name: agent
+        image: gcr.io/my-project/my-agent:latest
+        ports: [{containerPort: 8080}]
+        env:
+        - name: GOOGLE_API_KEY
+          valueFrom: {secretKeyRef: {name: google-api-key, key: key}}
+        resources:
+          requests: {memory: "2Gi", cpu: "1"}
+          limits: {memory: "4Gi", cpu: "2"}
+---
+apiVersion: v1
+kind: Service
+metadata: {name: my-agent}
+spec:
+  type: LoadBalancer
+  ports: [{port: 80, targetPort: 8080}]
+---
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata: {name: my-agent-hpa}
+spec:
+  scaleTargetRef: {kind: Deployment, name: my-agent}
+  minReplicas: 2
+  maxReplicas: 10
+  metrics:
+  - type: Resource
+    resource: {name: cpu, target: {type: Utilization, averageUtilization: 70}}
+```
+
+```bash
+gcloud container clusters create my-cluster --region us-central1 --num-nodes 3
+gcloud container clusters get-credentials my-cluster --region us-central1
+kubectl create secret generic google-api-key --from-literal=key=$GOOGLE_API_KEY
+kubectl apply -f deployment.yaml
+```
+
+## Best Practices
+
+```python
+# config.py
+import os
+from dataclasses import dataclass
+
+@dataclass
+class Config:
+  model_id: str = os.getenv('MODEL_ID', 'gemini-2.5-flash')
+  api_key: str = os.getenv('GOOGLE_API_KEY')
+  log_level: str = os.getenv('LOG_LEVEL', 'INFO')
+
+# Health checks
+@app.get('/health')
+async def health(): return {'status': 'healthy'}
+
+# Logging
+from google.cloud import logging
+client = logging.Client()
+client.setup_logging()
+
+# Rate limiting
+from slowapi import Limiter
+limiter = Limiter(key_func=get_remote_address)
+
+@app.post('/chat')
+@limiter.limit('10/minute')
+async def chat(request: Request, prompt: str):
+  return {'response': (await agent.run(prompt)).text}
+```

package/templates/skills/google-adk-python/references/evaluation-testing-cli.md

@@ -0,0 +1,112 @@
+# Evaluation, Testing, CLI
+
+## CLI Commands
+
+```bash
+adk web samples/agents/my_agent.py:agent --port 8080
+adk run samples/agents/my_agent.py:agent "What is 2+2?" --streaming
+adk api_server samples/agents/my_agent.py:agent --port 8000
+adk eval --agent my_agent.py:agent --evalset evals/evalset.json
+adk deploy --target cloud-run --agent my_agent.py:agent
+```
+
+## Evaluation
+
+### Evalset JSON
+
+```json
+{
+  "name": "math_evalset",
+  "test_cases": [
+    {"id": "add", "input": "2+2?", "expected_output": "4", "evaluation_type": "exact_match"},
+    {"id": "mult", "input": "5*6?", "expected_output": "30", "evaluation_type": "contains"},
+    {"id": "judge", "input": "(10+5)*2", "expected_output": "30", "evaluation_type": "llm_judge"}
+  ]
+}
+```
+
+Types: `exact_match`, `contains`, `regex`, `llm_judge`
+
+### Running Evals
+
+```python
+from google.adk.evaluation import Evaluator, EvalCase, EvalResult
+
+evaluator = Evaluator(agent=my_agent, evalset='evals/math.json')
+results = await evaluator.run()
+
+# Custom
+def custom_eval(case: EvalCase, response: str) -> EvalResult:
+    passed = response.strip().lower() == case.expected_output.lower()
+    return EvalResult(passed=passed, score=1.0 if passed else 0.0)
+
+evaluator = Evaluator(agent=my_agent, evalset='evals/custom.json', eval_fn=custom_eval)
+```
+
+## Testing
+
+```bash
+uv sync --extra test --extra eval --extra a2a
+pytest tests/unittests -n auto
+pytest tests/unittests --cov=google.adk
+```
+
+```python
+# conftest.py
+import pytest
+from google.adk.agents.web_agent import WebAgent
+
+@pytest.fixture
+def test_agent():
+    return WebAgent(name='test', model='gemini-2.5-flash')
+
+# test_agent.py
+@pytest.mark.asyncio
+async def test_basic():
+    agent = WebAgent(name='test', model='gemini-2.5-flash')
+    result = await agent.run('What is 2+2?')
+    assert '4' in result.text
+
+@pytest.mark.asyncio
+async def test_tools():
+    def calc(a: int, b: int) -> int: return a + b
+    agent = WebAgent(name='test', model='gemini-2.5-flash', tools=[calc])
+    result = await agent.run('Add 5 and 7')
+    assert '12' in result.text
+
+# Integration
+@pytest.mark.asyncio
+async def test_multi_turn():
+    agent = WebAgent(name='test', model='gemini-2.5-flash')
+    r1 = await agent.run('My name is Alice')
+    r2 = await agent.run('What is my name?')
+    assert 'Alice' in r2.text
+```
+
+## Formatting
+
+```bash
+./autoformat.sh
+pyink --line-length 80 --pyink-indentation 2 src/
+isort src/
+```
+
+## Style
+
+- Google Python Style Guide
+- 2-space indent, 80 chars
+- Type hints, docstrings
+
+```python
+def my_func(arg1: str, arg2: int) -> bool:
+  """Short description.
+
+  Args:
+    arg1: First
+    arg2: Second
+
+  Returns:
+    Result
+  """
+  return True
+```

package/templates/skills/google-adk-python/references/multi-agent-and-a2a-protocol.md

@@ -0,0 +1,145 @@
+# Multi-Agent and A2A Protocol
+
+## Sub-Agent Composition
+
+```python
+from google.adk.agents import Agent
+
+code_agent = Agent(
+    name="code_specialist", model="gemini-2.5-flash",
+    description="Code generation/debugging", tools=[executor, linter]
+)
+
+research_agent = Agent(
+    name="researcher", model="gemini-2.5-flash",
+    description="Web search/analysis", tools=[search, scraper]
+)
+
+root = Agent(
+    name="coordinator", model="gemini-2.5-flash",
+    instruction="Route tasks to specialists.",
+    sub_agents=[code_agent, research_agent]
+)
+```
+
+## Coordinator Pattern
+
+```python
+coordinator = Agent(
+    name="coordinator", model="gemini-2.5-flash",
+    instruction="Delegate: code_specialist (programming), data_analyst (data), writer (docs)",
+    sub_agents=[
+        Agent(name="code_specialist", model="gemini-2.5-flash", tools=[code_tools]),
+        Agent(name="data_analyst", model="gemini-2.5-flash", tools=[data_tools]),
+        Agent(name="writer", model="gemini-2.5-flash", tools=[writing_tools])
+    ]
+)
+```
+
+## RemoteA2aAgent
+
+```python
+from google.adk.agents.remote_a2a_agent import RemoteA2aAgent, AGENT_CARD_WELL_KNOWN_PATH
+
+prime_checker = RemoteA2aAgent(
+    name="prime", description="Check primes",
+    agent_card=f"http://localhost:8001{AGENT_CARD_WELL_KNOWN_PATH}"
+)
+
+root = Agent(
+    name="coordinator", model="gemini-2.5-flash",
+    sub_agents=[prime_checker, Agent(name="calc", model="gemini-2.5-flash", tools=[calc])]
+)
+```
+
+## Global Instruction
+
+```python
+root = Agent(
+    name="customer_service", model="gemini-2.5-flash",
+    instruction="Handle inquiries",
+    global_instruction="Be polite, follow privacy policy, escalate if uncertain",
+    sub_agents=[
+        Agent(name="billing", model="gemini-2.5-flash", tools=[billing]),
+        Agent(name="tech", model="gemini-2.5-flash", tools=[tech])
+    ]
+)
+```
+
+## Patterns
+
+### Pipeline
+
+```python
+from google.adk.agents import SequentialAgent
+
+pipeline = SequentialAgent(
+    name="content",
+    sub_agents=[
+        Agent(name="researcher", model="gemini-2.5-flash", tools=[search]),
+        Agent(name="writer", model="gemini-2.5-flash", tools=[write]),
+        Agent(name="editor", model="gemini-2.5-flash", tools=[edit])
+    ]
+)
+```
+
+### Parallel
+
+```python
+from google.adk.agents import ParallelAgent
+
+parallel = ParallelAgent(
+    name="multi_source",
+    sub_agents=[
+        Agent(name="web", model="gemini-2.5-flash", tools=[web]),
+        Agent(name="db", model="gemini-2.5-flash", tools=[db]),
+        Agent(name="api", model="gemini-2.5-flash", tools=[api])
+    ]
+)
+```
+
+### Hierarchical
+
+```python
+backend = Agent(name="backend", model="gemini-2.5-flash",
+    sub_agents=[Agent(name="api", tools=[api]), Agent(name="db", tools=[db])])
+frontend = Agent(name="frontend", model="gemini-2.5-flash",
+    sub_agents=[Agent(name="ui", tools=[ui]), Agent(name="ux", tools=[ux])])
+root = Agent(name="root", model="gemini-2.5-flash", sub_agents=[backend, frontend])
+```
+
+### Iterative
+
+```python
+from google.adk.agents import LoopAgent
+
+loop = LoopAgent(
+    name="review",
+    sub_agents=[
+        Agent(name="generator", model="gemini-2.5-flash", tools=[gen]),
+        Agent(name="reviewer", model="gemini-2.5-flash", tools=[lint])
+    ],
+    max_iterations=3
+)
+```
+
+## A2A Protocol
+
+```python
+from google.adk.servers.a2a_server import create_a2a_server
+app = create_a2a_server(root_agent)
+# Run: uvicorn my_agent:app --host 0.0.0.0 --port 8000
+```
+
+Agent card: `/.well-known/agent.json`
+
+Flow: 1) Client requests card 2) Card describes capabilities 3) Client sends task 4) Server streams events
+
+## Best Practices
+
+- Descriptive `description` for routing
+- Focused coordinator instructions
+- Combine local/remote agents
+- Use `global_instruction` for cross-cutting concerns
+- Apply workflow agents for orchestration
+- Cache remote cards, handle failures