hyunsoo's blog

Google ADK: Youtube shorts maker(1)- full code and agent pipleline

hyunsoo CHUNG — Mon, 5 Jan 2026 16:59:57 +0900

agent pipline

full code

YouTube Shorts Maker - Complete Code Collection

This document contains all Python code files from the project, organized by file path for easy copy-paste.

`youtube_shorts_maker/init.py`

from . import agent

`youtube_shorts_maker/agent.py`

from google.genai import types
from google.adk.agents import Agent
from google.adk.tools.agent_tool import AgentTool
from google.adk.models.lite_llm import LiteLlm
from .sub_agents.content_planner.agent import content_planner_agent
from .sub_agents.asset_generator.agent import asset_generator_agent
from .sub_agents.video_assembler.agent import video_assembler_agent
from .prompt import SHORTS_PRODUCER_DESCRIPTION, SHORTS_PRODUCER_PROMPT
from google.adk.agents.callback_context import CallbackContext
from google.adk.models.llm_request import LlmRequest
from google.adk.models.llm_response import LlmResponse

MODEL = LiteLlm(model="openai/gpt-4o")


def before_model_callback(
    callback_context: CallbackContext,
    llm_request: LlmRequest,
):
    history = llm_request.contents
    last_message = history[-1]
    if last_message.role == "user":
        text = last_message.parts[0].text
        if "hummus" in text:
            return LlmResponse(
                content=types.Content(
                    parts=[
                        types.Part(text="Sorry I can't help with that."),
                    ],
                    role="model",
                )
            )
    return None


shorts_producer_agent = Agent(
    name="ShortsProducerAgent",
    model=MODEL,
    description=SHORTS_PRODUCER_DESCRIPTION,
    instruction=SHORTS_PRODUCER_PROMPT,
    tools=[
        AgentTool(agent=content_planner_agent),
        AgentTool(agent=asset_generator_agent),
        AgentTool(agent=video_assembler_agent),
    ],
    before_model_callback=before_model_callback,
)

root_agent = shorts_producer_agent

`youtube_shorts_maker/prompt.py`

SHORTS_PRODUCER_DESCRIPTION = (
    "Primary orchestrator for creating vertical YouTube Shorts videos (9:16 portrait format) through a 5-phase workflow. "
    "Guides users through requirements gathering, coordinates specialized sub-agents in sequence "
    "(ContentPlanner → AssetGenerator → VideoAssembler), provides progress updates, "
    "handles error recovery, and delivers the final vertical MP4 video file."
)

SHORTS_PRODUCER_PROMPT = """
You are the ShortsProducerAgent, the primary orchestrator for creating vertical YouTube Shorts videos (9:16 portrait format).

## Your Workflow:
1. **Phase 1**: Greet user and gather requirements
2. **Phase 2**: Use ContentPlannerAgent to create structured script
3. **Phase 3**: Use AssetGeneratorAgent to generate images and audio in parallel
4. **Phase 4**: Use VideoAssemblerAgent to assemble final MP4 video
5. **Phase 5**: Present final result to user

## Important Guidelines:
- Always use agents in sequence: ContentPlanner → AssetGenerator → VideoAssembler
- Provide progress updates and handle errors gracefully
- Maintain a helpful and professional tone throughout

Begin by greeting the user and asking about their YouTube Short requirements.
"""

`youtube_shorts_maker/sub_agents/content_planner/agent.py`

from google.adk.agents import Agent
from google.adk.models.lite_llm import LiteLlm
from .prompt import CONTENT_PLANNER_DESCRIPTION, CONTENT_PLANNER_PROMPT
from pydantic import BaseModel, Field
from typing import List


class SceneOutput(BaseModel):
    id: int = Field(description="Scene ID number")
    narration: str = Field(description="Narration text for the scene")
    visual_description: str = Field(
        description="Detailed description for image generation"
    )
    embedded_text: str = Field(
        description="Text overlay for the image (can be any case/style)"
    )
    embedded_text_location: str = Field(
        description="Where to position the text on the image (e.g., 'top center', 'bottom left', 'middle right', 'center')"
    )
    duration: int = Field(description="Duration in seconds for this scene")


class ContentPlanOutput(BaseModel):
    topic: str = Field(description="The topic of the YouTube Short")
    total_duration: int = Field(description="Total video duration in seconds (max 20)")
    scenes: List[SceneOutput] = Field(
        description="List of scenes (agent decides how many)"
    )


MODEL = LiteLlm(model="openai/gpt-4o")

content_planner_agent = Agent(
    name="ContentPlannerAgent",
    description=CONTENT_PLANNER_DESCRIPTION,
    instruction=CONTENT_PLANNER_PROMPT,
    model=MODEL,
    output_schema=ContentPlanOutput,
    output_key="content_planner_output",
)

`youtube_shorts_maker/sub_agents/content_planner/prompt.py`

CONTENT_PLANNER_DESCRIPTION = (
    "Creates complete structured content plan for vertical YouTube Shorts videos (9:16 portrait format) in one step. "
    "Analyzes topic for key teaching points, determines optimal number of scenes and timing, "
    "generates narration text for each scene, designs vertical visual descriptions, "
    "and plans embedded text overlays. Outputs structured JSON format with max 20 seconds total."
)

CONTENT_PLANNER_PROMPT = """
You are the ContentPlannerAgent, responsible for creating complete structured content plans for vertical YouTube Shorts videos (9:16 portrait format).

## Your Task:
Given a topic from the user, create a comprehensive vertical YouTube Shorts script (9:16 portrait format) with a MAXIMUM of 20 seconds total duration.

## Output Format:
Return a valid JSON object with this structure:
{
  "topic": "[the provided topic]",
  "total_duration": "[sum of all scene durations - MUST be ≤ 20]",
  "scenes": [
    {
      "id": 1,
      "narration": "[narration text matching scene duration]",
      "visual_description": "[description for image generation]",
      "embedded_text": "[text overlay for image]",
      "embedded_text_location": "[position: top center, bottom left, etc.]",
      "duration": "[seconds for this scene]"
    }
  ]
}

## Guidelines:
- **CRITICAL**: Total duration MUST NOT exceed 20 seconds
- Scene count: 3-6 scenes typically work best
- Narration: Match word count to scene duration (2-3 words per second)
- Visual descriptions: Be specific for vertical image generation
- Embedded text: 2-8 words max, attention-grabbing, NO emojis

Return only the JSON object, no additional text.
"""

`youtube_shorts_maker/sub_agents/asset_generator/agent.py`

from google.adk.agents import ParallelAgent
from .prompt import ASSET_GENERATOR_DESCRIPTION
from .image_generator.agent import image_generator_agent
from .voice_generator.agent import voice_generator_agent

asset_generator_agent = ParallelAgent(
    name="AssetGeneratorAgent",
    description=ASSET_GENERATOR_DESCRIPTION,
    sub_agents=[
        image_generator_agent,
        voice_generator_agent,
    ],
)

`youtube_shorts_maker/sub_agents/asset_generator/prompt.py`

ASSET_GENERATOR_DESCRIPTION = (
    "Creates multimedia assets for vertical YouTube Shorts (9:16 portrait format) through parallel processing. Should ONLY be used after "
    "ContentPlannerAgent has completed and provided the structured script. "
    "Runs ImageGeneratorAgent (for vertical visual assets with embedded text) and VoiceGeneratorAgent "
    "(for narration audio) simultaneously to generate all required media assets."
)

`youtube_shorts_maker/sub_agents/asset_generator/image_generator/agent.py`

from google.adk.agents import SequentialAgent
from .prompt_builder.agent import prompt_builder_agent
from .image_builder.agent import image_builder_agent

image_generator_agent = SequentialAgent(
    name="ImageGeneratorAgent",
    sub_agents=[
        prompt_builder_agent,
        image_builder_agent,
    ],
)

`youtube_shorts_maker/sub_agents/asset_generator/image_generator/prompt_builder/agent.py`

from google.adk.agents import Agent
from google.adk.models.lite_llm import LiteLlm
from .prompt import PROMPT_BUILDER_DESCRIPTION, PROMPT_BUILDER_PROMPT
from pydantic import BaseModel, Field
from typing import List

MODEL = LiteLlm(model="openai/gpt-4o")


class OptimizedPrompt(BaseModel):
    scene_id: int = Field(description="Scene ID from the original content plan")
    enhanced_prompt: str = Field(
        description="Detailed prompt with technical specs and text overlay instructions for vertical YouTube Shorts"
    )


class PromptBuilderOutput(BaseModel):
    optimized_prompts: List[OptimizedPrompt] = Field(
        description="Array of optimized image generation prompts for vertical YouTube Shorts"
    )


prompt_builder_agent = Agent(
    name="PromptBuilderAgent",
    description=PROMPT_BUILDER_DESCRIPTION,
    instruction=PROMPT_BUILDER_PROMPT,
    model=MODEL,
    output_schema=PromptBuilderOutput,
    output_key="prompt_builder_output",
)

`youtube_shorts_maker/sub_agents/asset_generator/image_generator/prompt_builder/prompt.py`

PROMPT_BUILDER_DESCRIPTION = (
    "Analyzes visual descriptions from the content plan, adds technical specifications for vertical YouTube Shorts "
    "(9:16 portrait aspect ratio, 1080x1920), embeds text overlay instructions with positioning, "
    "and optimizes prompts for GPT-Image-1 model. Outputs array of optimized vertical image generation prompts."
)

PROMPT_BUILDER_PROMPT = """
You are the PromptBuilderAgent, responsible for transforming scene visual descriptions into optimized prompts for vertical YouTube Shorts image generation (9:16 portrait format).

## Your Task:
Take the structured content plan: {content_planner_output} and create optimized vertical image generation prompts for each scene.

## Input:
You will receive the content plan with scenes containing:
- visual_description: Basic description of what should be in the image
- embedded_text: Text that needs to be overlaid on the image
- embedded_text_location: Where the text should be positioned

## Process:
For each scene:
1. Analyze the visual description and enhance it with specific details
2. Add technical specifications: "9:16 portrait aspect ratio, 1080x1920 resolution, vertical composition"
3. Include embedded text instructions with precise positioning
4. Optimize for GPT-Image-1 model with style and quality keywords

## Output Format:
Return a JSON object:
{
  "optimized_prompts": [
    {
      "scene_id": 1,
      "enhanced_prompt": "[detailed prompt with technical specs and text overlay instructions]"
    }
  ]
}

## Guidelines:
- Always include technical specs: "9:16 portrait aspect ratio, 1080x1920 resolution, vertical composition, high quality, professional, YouTube Shorts format"
- Text overlay: Include "with bold, readable text '[TEXT]' positioned at [POSITION], with generous padding from borders"
- Style consistency: Maintain the same visual style, tone, and lighting across ALL prompts
"""

`youtube_shorts_maker/sub_agents/asset_generator/image_generator/image_builder/agent.py`

from google.adk.agents import Agent
from google.adk.models.lite_llm import LiteLlm
from .prompt import IMAGE_BUILDER_DESCRIPTION, IMAGE_BUILDER_PROMPT
from .tools import generate_images

MODEL = LiteLlm(model="openai/gpt-4o")

image_builder_agent = Agent(
    name="ImageBuilder",
    description=IMAGE_BUILDER_DESCRIPTION,
    instruction=IMAGE_BUILDER_PROMPT,
    model=MODEL,
    output_key="image_builder_output",
    tools=[
        generate_images,
    ],
)

`youtube_shorts_maker/sub_agents/asset_generator/image_generator/image_builder/prompt.py`

IMAGE_BUILDER_DESCRIPTION = (
    "Loops through each optimized prompt from PromptBuilderAgent, calls OpenAI GPT-Image-1 API "
    "to generate vertical YouTube Shorts images (9:16 portrait format), downloads and saves images"
    "Outputs array of generated image files with metadata."
)

IMAGE_BUILDER_PROMPT = """
You are the ImageBuilderAgent, responsible for generating vertical images for YouTube Shorts using OpenAI's GPT-Image-1 API.

## Your Task:
Generate vertical images for each scene using the optimized prompts from the previous agent.

## Process:
1. Use the generate_images tool to process all optimized prompts
2. Validate results and ensure all images are properly generated
3. Return metadata about the generated images

The tool will access optimized prompts containing:
- scene_id: Scene identifier from the content plan
- enhanced_prompt: Detailed prompt optimized for vertical YouTube Shorts generation
"""

`youtube_shorts_maker/sub_agents/asset_generator/image_generator/image_builder/tools.py`

import base64
from google.genai import types
from openai import OpenAI
from google.adk.tools.tool_context import ToolContext

client = OpenAI()


async def generate_images(tool_context: ToolContext):

    prompt_builder_output = tool_context.state.get("prompt_builder_output")
    optimized_prompts = prompt_builder_output.get("optimized_prompts")

    existing_artifacts = await tool_context.list_artifacts()

    generated_images = []

    for prompt in optimized_prompts:
        scene_id = prompt.get("scene_id")
        enhanced_prompt = prompt.get("enhanced_prompt")
        filename = f"scene_{scene_id}_image.jpeg"

        if filename in existing_artifacts:
            generated_images.append(
                {
                    "scene_id": scene_id,
                    "prompt": enhanced_prompt[:100],
                    "filename": filename,
                }
            )
            continue

        image = client.images.generate(
            model="gpt-image-1",
            prompt=enhanced_prompt,
            n=1,
            quality="low",
            moderation="low",
            output_format="jpeg",
            background="opaque",
            size="1024x1536",
        )

        image_bytes = base64.b64decode(image.data[0].b64_json)

        artifact = types.Part(
            inline_data=types.Blob(
                mime_type="image/jpeg",
                data=image_bytes,
            )
        )

        await tool_context.save_artifact(
            filename=filename,
            artifact=artifact,
        )

        generated_images.append(
            {
                "scene_id": scene_id,
                "prompt": enhanced_prompt[:100],
                "filename": filename,
            }
        )

    return {
        "total_images": len(generated_images),
        "generated_images": generated_images,
        "status": "complete",
    }

`youtube_shorts_maker/sub_agents/asset_generator/voice_generator/agent.py`

from google.adk.agents import Agent
from google.adk.models.lite_llm import LiteLlm
from .prompt import VOICE_GENERATOR_PROMPT, VOICE_GENERATOR_DESCRIPTION
from .tools import generate_narrations

MODEL = LiteLlm(model="openai/gpt-4o")

voice_generator_agent = Agent(
    name="VoiceGeneratorAgent",
    description=VOICE_GENERATOR_DESCRIPTION,
    instruction=VOICE_GENERATOR_PROMPT,
    model=MODEL,
    tools=[
        generate_narrations,
    ],
)

`youtube_shorts_maker/sub_agents/asset_generator/voice_generator/prompt.py`

VOICE_GENERATOR_DESCRIPTION = "Generates high-quality narration audio for vertical YouTube Shorts using OpenAI TTS API."

VOICE_GENERATOR_PROMPT = """
You are the VoiceGeneratorAgent, responsible for generating narration audio for YouTube Shorts using OpenAI's Text-to-Speech API.

## Content Plan:
{content_planner_output}

## Process:
1. Analyze the content plan to understand the topic, mood, and each scene's narration text
2. Select the best voice from OpenAI's options based on content mood:
   - **alloy**: Neutral, balanced tone
   - **echo**: Calm, soothing
   - **fable**: Warm, engaging for storytelling
   - **onyx**: Deep, authoritative
   - **nova**: Energetic, youthful
   - **shimmer**: Soft, gentle

3. Call the generate_narrations tool with:
   - Your selected voice
   - A list of dictionaries for each scene with:
     - input: the exact text to speak
     - instructions: combined instruction for speed and tone based on scene duration
     - scene_id: the scene number

## Voice Selection Guidelines:
- Cooking/Food: Use "fable" for warm, engaging instruction
- Fitness/Energy: Use "nova" for energetic, motivating tone
- Educational: Use "alloy" for clear, neutral delivery
- Professional/Business: Use "onyx" for authoritative tone

Extract narration text exactly from each scene in the content plan as "input".
"""

`youtube_shorts_maker/sub_agents/asset_generator/voice_generator/tools.py`

from google.genai import types
from openai import OpenAI
from google.adk.tools.tool_context import ToolContext
from typing import List, Dict, Any

client = OpenAI()


async def generate_narrations(
    tool_context: ToolContext, voice: str, voice_instructions: List[Dict[str, Any]]
):
    """
    Generate narration audio for each scene using OpenAI TTS API

    Args:
        tool_context: Tool context to access artifacts and save files
        voice: Selected voice for TTS (alloy, echo, fable, onyx, nova, shimmer)
        voice_instructions: List of dictionaries containing narration instructions for each scene

    Returns:
        Information about all generated audio files
    """

    existing_artifacts = await tool_context.list_artifacts()

    generated_narrations = []

    for instruction in voice_instructions:
        text_input = instruction.get("input")
        instructions = instruction.get("instructions")
        scene_id = instruction.get("scene_id")
        filename = f"scene_{scene_id}_narration.mp3"

        if filename in existing_artifacts:
            generated_narrations.append(
                {
                    "scene_id": scene_id,
                    "filename": filename,
                    "input": text_input,
                    "instructions": instructions[:50],
                }
            )
            continue

        with client.audio.speech.with_streaming_response.create(
            model="gpt-4o-mini-tts",
            voice=voice,
            input=text_input,
            instructions=instructions,
        ) as response:

            audio_data = response.read()

        artifact = types.Part(
            inline_data=types.Blob(mime_type="audio/mpeg", data=audio_data)
        )

        await tool_context.save_artifact(filename=filename, artifact=artifact)

        generated_narrations.append(
            {
                "scene_id": scene_id,
                "filename": filename,
                "input": text_input,
                "instructions": instructions[:50],
            }
        )

    return {
        "total_narrations": len(generated_narrations),
        "generated_narrations": generated_narrations,
        "status": "complete",
    }

`youtube_shorts_maker/sub_agents/video_assembler/agent.py`

from google.adk.agents import Agent
from google.adk.models.lite_llm import LiteLlm
from .prompt import VIDEO_ASSEMBLER_DESCRIPTION, VIDEO_ASSEMBLER_PROMPT
from .tools import assemble_video

MODEL = LiteLlm(model="openai/gpt-4o")

video_assembler_agent = Agent(
    name="VideoAssemblerAgent",
    model=MODEL,
    description=VIDEO_ASSEMBLER_DESCRIPTION,
    instruction=VIDEO_ASSEMBLER_PROMPT,
    output_key="video_assembler_output",
    tools=[
        assemble_video,
    ],
)

`youtube_shorts_maker/sub_agents/video_assembler/prompt.py`

VIDEO_ASSEMBLER_DESCRIPTION = (
    "Final step agent that assembles generated image and audio artifacts into a complete vertical YouTube Shorts video. "
    "Should be used ONLY after both image generation and voice generation are complete and all scene assets exist as artifacts. "
    "Reads content plan timing, locates all media artifacts, and executes video assembly to produce final MP4 output."
)

VIDEO_ASSEMBLER_PROMPT = """
You are the VideoAssemblerAgent, responsible for creating the final YouTube Shorts video from generated assets.

## Your Task:
Use the assemble_video tool to create the final vertical YouTube Shorts video from all the generated image and audio artifacts.

## Process:
1. Call the assemble_video tool
2. The tool will automatically:
   - Read the content plan timing from context
   - Locate all image and audio artifacts
   - Execute FFmpeg assembly with proper vertical formatting
   - Create the final MP4 video

## Important:
- Only use this agent after all images and audio files have been generated
- The tool handles all technical details including timing, formatting, and FFmpeg execution
- Report the results of the video assembly process
"""

`youtube_shorts_maker/sub_agents/video_assembler/tools.py`

"""Tools for VideoAssemblerAgent"""

import subprocess
import re
import tempfile
import os
from google.adk.tools.tool_context import ToolContext
import google.genai.types as types


async def assemble_video(tool_context: ToolContext) -> str:
    """Assemble final YouTube Shorts video from image and audio artifacts

    Args:
        tool_context: Tool context to access state and artifacts

    Returns:
        Information about the video assembly process
    """
    temp_files = []  # Track temporary files for cleanup

    try:
        # Read content plan from context
        content_planner_output = tool_context.state.get("content_planner_output", {})
        scenes = content_planner_output.get("scenes", [])

        if not scenes:
            return "No scenes found in content plan"

        print(f"  VIDEO ASSEMBLER: Starting assembly for {len(scenes)} scenes")

        # List all available artifacts
        existing_artifacts = await tool_context.list_artifacts()

        # Find image and audio files
        image_files = []
        audio_files = []

        for artifact_name in existing_artifacts:
            if artifact_name.startswith("scene_") and artifact_name.endswith(
                "_image.jpeg"
            ):
                image_files.append(artifact_name)
            elif artifact_name.startswith("scene_") and artifact_name.endswith(
                "_narration.mp3"
            ):
                audio_files.append(artifact_name)

        # Sort by scene number
        def extract_scene_number(filename):
            match = re.search(r"scene_(\d+)_", filename)
            return int(match.group(1)) if match else 0

        image_files.sort(key=extract_scene_number)
        audio_files.sort(key=extract_scene_number)

        print(f" ️ Found {len(image_files)} image artifacts")
        print(f"  Found {len(audio_files)} audio artifacts")

        if len(image_files) != len(scenes) or len(audio_files) != len(scenes):
            return f"Missing artifacts: Expected {len(scenes)} images and audio files, found {len(image_files)} images and {len(audio_files)} audio files"

        # Load artifacts and create temporary files
        temp_image_paths = []
        temp_audio_paths = []

        for i, (image_name, audio_name) in enumerate(zip(image_files, audio_files)):
            # Load and save image artifact
            print(f"  Loading image artifact: {image_name}")
            image_artifact = await tool_context.load_artifact(filename=image_name)
            if image_artifact and image_artifact.inline_data:
                temp_image = tempfile.NamedTemporaryFile(suffix=".jpeg", delete=False)
                temp_image.write(image_artifact.inline_data.data)
                temp_image.close()
                temp_image_paths.append(temp_image.name)
                temp_files.append(temp_image.name)
                print(f"  Created temp image: {temp_image.name}")
            else:
                return f"Failed to load image artifact: {image_name}"

            # Load and save audio artifact
            print(f"  Loading audio artifact: {audio_name}")
            audio_artifact = await tool_context.load_artifact(filename=audio_name)
            if audio_artifact and audio_artifact.inline_data:
                temp_audio = tempfile.NamedTemporaryFile(suffix=".mp3", delete=False)
                temp_audio.write(audio_artifact.inline_data.data)
                temp_audio.close()
                temp_audio_paths.append(temp_audio.name)
                temp_files.append(temp_audio.name)
                print(f"  Created temp audio: {temp_audio.name}")
            else:
                return f"Failed to load audio artifact: {audio_name}"

        # Build FFmpeg command with temporary file paths
        input_args = []
        filter_parts = []

        # Add inputs for each scene
        for i, (temp_image, temp_audio) in enumerate(
            zip(temp_image_paths, temp_audio_paths)
        ):
            input_args.extend(["-i", temp_image, "-i", temp_audio])

            # Get scene duration from content plan
            scene_duration = scenes[i].get("duration", 4)  # fallback to 4 seconds

            # Create video stream that displays image for scene duration
            total_frames = int(30 * scene_duration)  # 30fps * duration in seconds
            filter_parts.append(
                f"[{i*2}:v]scale=1080:1920:force_original_aspect_ratio=decrease,"
                f"pad=1080:1920:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=30,"
                f"loop={total_frames-1}:size=1:start=0[v{i}]"
            )

            # Keep audio as-is
            filter_parts.append(f"[{i*2+1}:a]anull[a{i}]")

        # Concatenate all video and audio streams
        video_inputs = "".join([f"[v{i}]" for i in range(len(scenes))])
        audio_inputs = "".join([f"[a{i}]" for i in range(len(scenes))])
        filter_parts.append(f"{video_inputs}concat=n={len(scenes)}:v=1:a=0[outv]")
        filter_parts.append(f"{audio_inputs}concat=n={len(scenes)}:v=0:a=1[outa]")

        # Create temporary output file
        temp_output = tempfile.NamedTemporaryFile(suffix=".mp4", delete=False)
        temp_output.close()
        output_path = temp_output.name
        temp_files.append(output_path)

        # Build final FFmpeg command
        ffmpeg_cmd = (
            ["ffmpeg", "-y"]
            + input_args
            + [
                "-filter_complex",
                ";".join(filter_parts),
                "-map",
                "[outv]",
                "-map",
                "[outa]",
                "-c:v",
                "libx264",
                "-c:a",
                "aac",
                "-pix_fmt",
                "yuv420p",
                "-r",
                "30",
                output_path,
            ]
        )

        print("  Executing FFmpeg command...")
        print(" ".join(ffmpeg_cmd))

        # Execute FFmpeg
        subprocess.run(ffmpeg_cmd, capture_output=True, text=True, check=True)

        # Save final video as artifact
        with open(output_path, "rb") as f:
            video_data = f.read()

        artifact = types.Part(
            inline_data=types.Blob(mime_type="video/mp4", data=video_data)
        )

        await tool_context.save_artifact(
            filename="youtube_short_final.mp4", artifact=artifact
        )

        total_duration = sum(scene.get("duration", 4) for scene in scenes)

        result_info = {
            "status": "success",
            "scenes_processed": len(scenes),
            "total_duration": total_duration,
            "output_file": "youtube_short_final.mp4",
            "resolution": "1080x1920",
            "format": "MP4 (H.264/AAC)",
        }

        print(f"✅ Video assembly complete! Created {total_duration}s YouTube Short")
        return str(result_info)

    except subprocess.CalledProcessError as e:
        error_info = {
            "status": "ffmpeg_error",
            "error_message": str(e),
            "stderr": e.stderr,
            "stdout": e.stdout,
        }
        print(f"❌ FFmpeg failed: {e.stderr}")
        return str(error_info)

    except Exception as e:
        error_info = {"status": "error", "error_message": str(e)}
        print(f"❌ Video assembly failed: {str(e)}")
        return str(error_info)

    finally:
        # Clean up temporary files
        for temp_file in temp_files:
            try:
                if os.path.exists(temp_file):
                    os.unlink(temp_file)
                    print(f" ️ Cleaned up temp file: {temp_file}")
            except Exception as e:
                print(f"⚠️ Failed to cleanup {temp_file}: {e}")

Summary

This collection includes:

19 Python files organized by file path
Agent definitions with Pydantic schemas
Tool implementations using ToolContext
Prompt files condensed to essential context and core instructions
Callback implementation example

All code is ready for copy-paste into blog posts or documentation.

Google ADK: Financial Advisor(4)- state, artifact, toolcontext

hyunsoo CHUNG — Sat, 3 Jan 2026 03:12:13 +0900

Step 6: Save Report (Optional)

6-1. Main Agent LLM Call #12 (Report Generation)

Response received by Google ADK from OpenAI GPT-4o API (LLM Response #12):

JSON

{
  "tool_calls": [
    {
      "id": "call_401",
      "function": {
        "name": "save_advice_report",
        "arguments": "{\"summary\": \"[Final Advice Text]\", \"ticker\": \"AAPL\"}"
      }
    }
  ]
}

Generator: OpenAI GPT-4o LLM (for Main Agent) Receiver: Google ADK (Main Agent System)

Role and Impact of this JSON: This JSON is the result of the LLM deciding to save a report after generating the final advice.

Role in the Overall Process:

Report Save Trigger: Triggered because the user requested a report, or the LLM judged that saving a report was necessary.
Process Conclusion: Permanently saves the results after all analysis and advice are complete.
Tool Call: Calls the save_advice_report function to create the file.

What happens via this JSON:

Google ADK calls the save_advice_report function.
The function reads the results of all sub-agents from the state.
The function creates a comprehensive report in Markdown format.
The function saves it as an Artifact, storing it permanently in the file system.

Impact:

Permanent Preservation: The report remains as a file even after the session ends, allowing for future reference.
User Experience: Provides a file that users can download or share.
Full System Termination: All tasks are completed, and the system fully terminates.

Confusing Parts:

arguments contains summary and ticker. summary is the final advice text generated by the LLM.
Why does the LLM decide to save the report? → Although the prompt says "use ONLY when user requests a report," the LLM may decide to do so based on the context.
Why is all data in the state at this point? → Because each sub-agent saved its results to the state using output_key.

6-2. Report Saving Function Execution

Function Execution: save_advice_report(tool_context, summary, "AAPL")

Python Function Execution (save_advice_report):

Python

# Executing save_advice_report function in agent.py

# 1. Access State
state = tool_context.state  # Get state object from ToolContext

# 2. Read results of each sub-agent from State
data_analyst_result = state.get("data_analyst_result")           # Value saved via output_key="data_analyst_result"
financial_analyst_result = state.get("financial_analyst_result") # Value saved via output_key="financial_analyst_result"
news_analyst_result = state.get("news_analyst_analyst_result")   # Value saved via output_key="news_analyst_result"

# State status at this point:
# {
#     "data_analyst_result": "**Company Overview:**\nApple Inc. ...",
#     "financial_analyst_result": "**Income Statement Analysis:**\nTotal Revenue ...",
#     "news_analyst_result": "**Recent News Analysis:**\n1. Strong Q4 Earnings ..."
# }

# 3. Generate Comprehensive Report (Markdown String)
report = f"""
# Executive Summary and Advice:
{summary}

## Data Analyst Report:
{data_analyst_result}

## Financial Analyst Report:
{financial_analyst_result}

## News Analyst Report:
{news_analyst_result}
"""

# 4. Save to State as well (Optional - for future access)
state["report"] = report

# 5. Generate Filename
filename = f"{ticker}_investment_advice.md"  # "AAPL_investment_advice.md"

# 6. Create Artifact Object
artifact = types.Part(
    inline_data=types.Blob(
        mime_type="text/markdown",  # Specify MIME type (Markdown file)
        data=report.encode("utf-8"),  # Encode string to UTF-8 bytes
        # report.encode("utf-8") result: b'# Executive Summary...'
    )
)

# 7. Save Artifact (Async - Save to file system)
await tool_context.save_artifact(filename, artifact)
# → Saved to path: .adk/artifacts/users/user/sessions/{session_id}/artifacts/AAPL_investment_advice.md/versions/0/

# 8. Function Return Value
return {"success": True}

Generator: Python function save_advice_report - Collect data from State (state.get()) - Create Artifact object (types.Part, types.Blob) - Create file content (Markdown string) Storage Location: Google ADK Artifact Storage Storage Path: .adk/artifacts/users/{user_id}/sessions/{session_id}/artifacts/{filename}/versions/0/

Result:

The AAPL_investment_advice.md file is created and stored in the Google ADK artifact storage.
It is also saved in the State under the key state["report"] (Optional).

(For details on State and Artifacts, refer to the "State Management System Detailed Description" and "Artifact System Detailed Description" sections below)

Total LLM Call Summary

In this example, a total of 12 LLM calls occurred:

Main Agent LLM Call #1: Initial request analysis → Decision to call data_analyst
Data Analyst LLM Call #2: Decision to call tools (get_company_info, get_stock_price, get_financial_metrics)
Data Analyst LLM Call #3: Generation of data analysis result text
Main Agent LLM Call #4: Decision to call financial_analyst
Financial Analyst LLM Call #5: Decision to call financial statement tools
Financial Analyst LLM Call #6: Generation of financial statement analysis result text
Main Agent LLM Call #7: Decision to call news_analyst
News Analyst LLM Call #8: Decision to call web_search_tool
News Analyst LLM Call #9: Generation of news analysis result text
Main Agent LLM Call #10: Generation of user preference questions
Main Agent LLM Call #11: Generation of final investment advice
Main Agent LLM Call #12: Decision to call report saving tool

ToolContext Detailed Description

ToolContext is a context object automatically passed by Google ADK when calling a tool function. It provides information and functionality regarding the environment (context) in which the tool function is executed.

Role of ToolContext

ToolContext performs the following important roles:

Provide State Access: Access session state via tool_context.state.
Artifact Saving Function: Save files via the tool_context.save_artifact() method.
Execution Context Information: Provide context information for the currently running tool function.

How ToolContext is Passed

Important: ToolContext is automatically passed by Google ADK. Developers do not need to create or pass it manually.

When Defining Tool Functions: If you specify ToolContext as the first parameter type when defining a tool function, Google ADK automatically passes it when the function is called:

Python

from google.adk.tools import ToolContext

# Specify ToolContext as the first parameter
async def save_advice_report(tool_context: ToolContext, summary: str, ticker: str):
    # tool_context is automatically passed by Google ADK
    state = tool_context.state  # Access State
    await tool_context.save_artifact(...)  # Save Artifact

Google ADK Internal Operation:

LLM Decides to Call Tool Function:

JSON

{
  "tool_calls": [{
    "function": {
      "name": "save_advice_report",
      "arguments": "{\"summary\": \"...\", \"ticker\": \"AAPL\"}"
    }
  }]
}

Google ADK Calls Function:

Python

# Executed internally by Google ADK (Pseudocode)
tool_context = ToolContext(...)  # Google ADK creates ToolContext object
await save_advice_report(
    tool_context,  # ← Passed automatically
    summary="...",  # Parameter decided by LLM
    ticker="AAPL"   # Parameter decided by LLM
)

Major Properties and Methods of ToolContext

1. tool_context.state

Role: Access the session's state dictionary.
Features:
- Behaves like a Python dictionary (dict).
- Data storage maintained during the session.
- All tool functions access the same state object (Data Sharing).
Usage Example:

Python

async def my_tool(tool_context: ToolContext, ...):
    state = tool_context.state  # Get State object

    # Read State
    value = state.get("key")  # Returns None if key doesn't exist
    value = state["key"]      # Raises KeyError if key doesn't exist

    # Write State
    state["key"] = "value"    # Save value to State

2. tool_context.save_artifact(filename, artifact)

Role: Save an Artifact (File) to Google ADK storage.
Features:
- Asynchronous function (await required).
- Saves the file to Google ADK's artifact storage.
- Stored permanently (persists even after the session ends).
Usage Example:

Python

async def my_tool(tool_context: ToolContext, ...):
    # Create Artifact Object
    artifact = types.Part(
        inline_data=types.Blob(
            mime_type="text/markdown",
            data=content.encode("utf-8"),
        )
    )
    # Save Artifact (Async)
    await tool_context.save_artifact("report.md", artifact)

ToolContext Passing Conditions

Function Receiving ToolContext (Tool Function):

Python

from google.adk.tools import ToolContext

async def save_advice_report(tool_context: ToolContext, summary: str, ticker: str):
    # tool_context is available
    state = tool_context.state
    await tool_context.save_artifact(...)

Function Not Receiving ToolContext (General Tool Function):

Python

def get_company_info(ticker: str):
    # ToolContext is not needed
    stock = yf.Ticker(ticker)
    return {"ticker": ticker, "company_name": stock.info.get("longName")}

Difference:

If State or Artifact features are needed: Receive ToolContext as the first parameter.
If only simple data lookup/processing is done: ToolContext is unnecessary.

Lifecycle of ToolContext

Creation: Created by Google ADK when a tool function is called.
Passing: Automatically passed as the first parameter of the tool function.
Usage: Used within the tool function to access state, save artifacts, etc.
Destruction: When function execution ends, the context is maintained, but a new ToolContext is created for the next function call.

Important: Although a new ToolContext is created for each tool function call, the state is shared throughout the session.

State Management System Detailed Description

What is State?

State is the central repository for sharing data between agents in Google ADK. It behaves similarly to a Python dictionary (dict) and persists for the duration of a session.

Creation and Access of State

1. Access via ToolContext.state

All tool functions can access the state by receiving the ToolContext object as the first parameter:

Python

async def save_advice_report(tool_context: ToolContext, summary: str, ticker: str):
    state = tool_context.state  # Access state object via ToolContext
    # state can be used like a dict
    data = state.get("data_analyst_result")

Important: State can only be accessed via ToolContext. You cannot access state without ToolContext.

2. Structure of State

State basically behaves identically to a Python dictionary:

Python

state = {
    "data_analyst_result": "...",       # Analysis result in string format
    "financial_analyst_result": "...",  # Analysis result in string format
    "news_analyst_result": "...",       # Analysis result in string format
    "report": "...",                    # Final report (Optional)
    # ... other key-value pairs
}

Auto-save via output_key

When a sub-agent receives a final text response from the LLM, it is automatically saved to the state with the key specified in output_key.

Actual Code Example

Data Analyst Agent Definition (financial_advisor/sub_agents/data_analyst.py):

Python

data_analyst = LlmAgent(
    name="DataAnalyst",
    model=MODEL,
    tools=[get_company_info, get_stock_price, get_financial_metrics],
    output_key="data_analyst_result",  # ← Saved to state with this key
)

Operational Process:

Data Analyst Agent receives text response from LLM: "**Company Overview:**\nApple Inc. is a technology company..."
Google ADK automatically saves to state:

Python

# Automatically executed internally by Google ADK
state["data_analyst_result"] = "**Company Overview:**\nApple Inc. is a technology company..."

Main Agent or other functions can access state:

Python

async def save_advice_report(tool_context: ToolContext, ...):
    state = tool_context.state
    data_analyst_result = state.get("data_analyst_result")  # Read saved value

Step-by-Step State Changes

Initial State (Session Start):
Python
```
state = {}  # Empty dictionary
```
After Data Analyst Agent Execution:

Python

state = {
  "data_analyst_result": """
  **Company Overview:**
  Apple Inc. is a technology company in the Consumer Electronics industry.
  ...
  """
}

After Financial Analyst Agent Execution:

Python

state = {
  "data_analyst_result": "...",
  "financial_analyst_result": """
  **Income Statement Analysis:**
  Total Revenue (2024): $383.3 billion
  ...
  """
}

After News Analyst Agent Execution:

Python

state = {
  "data_analyst_result": "...",
  "financial_analyst_result": "...",
  "news_analyst_result": """
  **Recent News Analysis:**
  1. Strong Q4 Earnings: Apple reported $89.5B revenue...
  ...
  """
}

After save_advice_report Function Execution:

Python

state = {
  "data_analyst_result": "...",
  "financial_analyst_result": "...",
  "news_analyst_result": "...",
  "report": """
  # Executive Summary and Advice:
  [Final Advice Text]
  ## Data Analyst Report:
  [Content of data_analyst_result]
  ...
  """
}

Characteristics of State

Session-based: State exists independently for each user session.
Key-Value Storage: Consists of string keys and string values (Agent responses are all text).
Auto-save: If output_key is specified, the agent's final response is automatically saved.
Read/Write: Accessible in tool functions via state.get(key), state[key] = value, etc.

Artifact System Detailed Description

What is an Artifact?

Artifact is a system for storing and managing files in Google ADK. It allows permanent storage of final deliverables generated by agents (reports, images, data files, etc.).

Artifact Creation Process

1. Creating an Artifact Object

Google ADK uses the google.genai.types module to create Artifact objects:

Python

from google.genai import types

# Create Artifact (Markdown file example)
artifact = types.Part(
    inline_data=types.Blob(
        mime_type="text/markdown",  # Specify file type
        data=report.encode("utf-8"),  # File content (bytes format)
    )
)

Component Explanation:

types.Part: Container for the Artifact.
types.Blob: Object containing the actual data.
- mime_type: MIME type of the file (e.g., "text/markdown", "text/plain", "image/png", "application/json").
- data: Data encoded into bytes sequence.

2. Detailed Steps for Saving an Artifact (Code Analysis)

Step 1: Collect Data

Python

state = tool_context.state
data_analyst_result = state.get("data_analyst_result") # Read from State

Step 2: Combine Text

Python

report = f"""
# Executive Summary and Advice:
{summary}
...
"""

Use Python f-strings to combine multiple state values into a single Markdown string.
summary is the value received as a function parameter.

Step 3: Save to State (Optional)

Python

state["report"] = report

Can be saved to state separately from the Artifact.

Step 4: Generate Filename

Python

filename = f"{ticker}_investment_advice.md"

Example: "AAPL_investment_advice.md".

Step 5: Create Artifact Object

Python

artifact = types.Part(
    inline_data=types.Blob(
        mime_type="text/markdown",
        data=report.encode("utf-8"),
    )
)

Details:
- report.encode("utf-8"): Converts string to bytes via UTF-8 encoding.
- mime_type="text/markdown": Specifies that the file is in Markdown format.

Step 6: Asynchronous Save

Python

await tool_context.save_artifact(filename, artifact)

Details:
- Use await keyword as it is an asynchronous function.
- The file is saved to Google ADK's artifact storage.

Artifact Storage Location

Artifacts are stored in the following directory structure:

.adk/
  artifacts/
    users/
      {user_id}/
        sessions/
          {session_id}/
            artifacts/
              {filename}/
                versions/
                  0/
                    metadata.json
                    (Actual File)

Example Path: .adk/artifacts/users/user/sessions/9122902d-0d69-4b6d-85ae-e5254418b9d0/artifacts/AAPL_investment_advice.md/versions/0/

Difference between Artifact and State

Feature	State	Artifact
Storage Form	In-memory Dictionary (Key-Value)	Files in File System
Data Type	String (Text)	Bytes (Binary data allowed)
Persistence	Maintained only during session	Permanent storage (Saved as file)
Access Method	state.get(key), state[key]	File download or path access
Usage	Data sharing between agents	Storage of final deliverables (reports, images)
Auto-save	Can save automatically via output_key	Requires manual save_artifact() call

Sheets로 내보내기

Relationship between State and Artifact

In real usage scenarios, State and Artifact are used together:

State: Sharing intermediate results between agents.
- Data Analyst → state["data_analyst_result"]
- Financial Analyst → state["financial_analyst_result"]
- News Analyst → state["news_analyst_result"]
Artifact: Saving final deliverables as files.
- The save_advice_report() function reads all data from the state,
- Combines it into a single Markdown file,
- And saves it as an Artifact.

Tool Function Parameter Determination Method

Core Concept: The LLM automatically determines parameters.

Question: In the get_stock_price(ticker: str, period: str) function used by data_analyst, who decides the period parameter value ("1y", "3mo", etc.)? Answer: The Agent (LLM) decides automatically!

Operating Principle

At Function Registration Time:

Python

# data_analyst.py
data_analyst = LlmAgent(
    tools=[
        get_company_info,      # Pass function object itself
        get_stock_price,       # Pass function object itself
        get_financial_metrics,
    ],
)

Google ADK Automatic Processing:
- Google ADK parses the docstring of the registered functions.
- It reads the function signature (def get_stock_price(ticker: str, period: str)) and the docstring.
- It sends the function description and parameter information to the LLM in JSON Schema format.
Example Information Sent to LLM:

JSON

{
  "type": "function",
  "function": {
    "name": "get_stock_price",
    "description": "Fetches historical stock price data and current trading price for a given ticker.",
    "parameters": {
      "type": "object",
      "properties": {
        "ticker": {
          "type": "string",
          "description": "Stock ticker symbol (e.g., 'AAPL' for Apple Inc.)"
        },
        "period": {
          "type": "string",
          "description": "Time period for historical data. Valid options: '1d', '5d', '1mo', '3mo', '6mo', '1y', '2y', '5y', '10y', 'ytd', 'max'"
        }
      },
      "required": ["ticker", "period"]
    }
  }
}

LLM Determines Parameter Values:
- The LLM determines appropriate values based on the user request, context, and function description.
- Example: Request "Analyze AAPL stock" → LLM decides {"ticker": "AAPL", "period": "1y"}.

Actual Example

Scenario: User requests "Analyze AAPL stock".

Data Analyst agent decides it needs to use the get_stock_price tool.
LLM reads and understands the function description:
- ticker is a required parameter → Use "AAPL".
- period is optional but necessary for analysis → LLM selects "1y" (1 year) based on context.
LLM Response:

JSON

{
  "tool_calls": [{
    "function": {
      "name": "get_stock_price",
      "arguments": "{\"ticker\": \"AAPL\", \"period\": \"1y\"}"
    }
  }]
}

Google ADK parses this JSON and calls the actual Python function:

Python

get_stock_price(ticker="AAPL", period="1y")  # Called with values decided by LLM

Important Points

Function docstrings are extremely important: The LLM uses them to understand the function and generate correct parameters. Detailed docstrings are essential.
Type Hints are also utilized: The str type hint in def get_stock_price(ticker: str, period: str) is passed to the LLM.
Intelligent Judgment by LLM: The LLM doesn't just call the function; it judges what parameter values are appropriate. (e.g., "3mo" for short-term analysis requests, "2y" for long-term).

Data Flow Diagram

User Input
    ↓
Main Agent (LLM #1)
    ↓
[Tool Call: data_analyst]
    ↓
Data Analyst Agent (LLM #2)
    ↓
[Tool Execution: get_company_info, get_stock_price, get_financial_metrics]
    ↓ (Yahoo Finance API)
Data Analyst (LLM #3) → state["data_analyst_result"]
    ↓
Main Agent (LLM #4)
    ↓
[Tool Call: financial_analyst]
    ↓
Financial Analyst Agent (LLM #5)
    ↓
[Tool Execution: get_income_statement, get_balance_sheet, get_cash_flow]
    ↓ (Yahoo Finance API)
Financial Analyst (LLM #6) → state["financial_analyst_result"]
    ↓
Main Agent (LLM #7)
    ↓
[Tool Call: news_analyst]
    ↓
News Analyst Agent (LLM #8)
    ↓
[Tool Execution: web_search_tool]
    ↓ (Firecrawl API)
News Analyst (LLM #9) → state["news_analyst_result"]
    ↓
Main Agent (LLM #10, #11)
    ↓
[Final Advice Generation]
    ↓
[Optional: save_advice_report]
    ↓
Markdown File Save

Google ADK: Financial Advisor(3)- json communication between llm and adk

hyunsoo CHUNG — Sat, 3 Jan 2026 03:09:26 +0900

System Overview

This system is a financial advisory system utilizing a multi-agent architecture. The main agent (Financial Advisor) coordinates three specialized sub-agents to provide comprehensive investment analysis.

Financial Advisor (Main Agent)
├── Data Analyst (Basic Data Collection)
├── Financial Analyst (Financial Statement Analysis)
├── News Analyst (News Search and Analysis)
└── save_advice_report (Save Final Report)

Real-world Example: AAPL Stock Analysis Request

Explaining the case where a user asks, "Give me investment advice for AAPL stock."

Detailed Step-by-Step Process

Step 1: Receiving User Request and Initial LLM Call

User Input

"Give me investment advice for AAPL stock"

Main Agent LLM Call #1

Call Location: financial_advisor agent in financial_advisor/agent.py LLM Model: openai/gpt-4o (Call via LiteLlm) Request Sent from Google ADK → OpenAI GPT-4o API:

JSON

{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "You are a Professional Financial Advisor... [Entire content of PROMPT from prompt.py]"
    },
    {
      "role": "user",
      "content": "Give me investment advice for AAPL stock"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "data_analyst",
        "description": "Gathers and analyzes basic stock market data..."
      }
    },
    {
      "type": "function",
      "function": {
        "name": "financial_analyst",
        "description": "Analyzes detailed financial statements..."
      }
    },
    {
      "type": "function",
      "function": {
        "name": "news_analyst",
        "description": "Uses Web Search tools to search and scrape real web content..."
      }
    },
    {
      "type": "function",
      "function": {
        "name": "save_advice_report",
        "description": "Save comprehensive reports as artifacts..."
      }
    }
  ]
}

Generator: Google ADK (Main Agent System) Receiver: OpenAI GPT-4o API

Role and Impact of this JSON: This JSON serves as the Entry Point of the system, passing the user request to the LLM for the first time.

Role in the Overall Process:

Context Setting: Provides the LLM with the Financial Advisor role and behavioral guidelines (prompt).
Tool List Provision: Introduces the 4 tools available to the LLM (3 Sub-agents + save_advice_report).
User Intent Delivery: Conveys the actual user request ("Give me investment advice for AAPL stock").

What happens via this JSON:

OpenAI GPT-4o API receives this request and passes it to the LLM model.
The LLM reads the prompt to understand the Financial Advisor role.
The LLM analyzes the user request and reviews the available tools.
The LLM secures all information needed to decide the next step (which tool to call).

Impact:

Directly influences the LLM's next decision (which sub-agent to call).
The content of the prompt determines the LLM's behavior pattern.
Tools not in the list cannot be used by the LLM (provides constraints).

Confusing Parts:

The tools array does not show parameter schemas here because Google ADK handles sub-agents internally.
system.content actually contains the entire 55 lines from prompt.py, but is abbreviated in the documentation for readability.

Response received by Google ADK from OpenAI GPT-4o API:

JSON

{
  "tool_calls": [
    {
      "id": "call_123",
      "type": "function",
      "function": {
        "name": "data_analyst",
        "arguments": "{\"ticker\": \"AAPL\"}"
      }
    }
  ],
  "finish_reason": "tool_calls"
}

Generator: OpenAI GPT-4o LLM Receiver: Google ADK (Main Agent System)

Role and Impact of this JSON: This JSON is the result of the LLM's decision-making after analyzing the initial request.

Role in the Overall Process:

Decision Result: Expresses the LLM's decision to "call the data_analyst first."
Next Step Trigger: When Google ADK receives this response, it initiates the execution of the data_analyst sub-agent.
Chain Start Point: Signal to start the first step of the entire multi-agent process.

What happens via this JSON:

Google ADK parses the tool_calls array to recognize the need to call data_analyst.
Google ADK extracts the ticker: "AAPL" parameter from arguments.
Google ADK executes the Data Analyst sub-agent, passing ticker="AAPL".
The Data Analyst sub-agent begins its task.

Impact:

Process Branching Point: At this point, the flow of the main agent branches into the Data Analyst sub-agent.
Sequential Execution Decision: The LLM decided to execute sequentially rather than calling multiple tools at once (influenced by "ANALYSIS METHODOLOGY" in the prompt).
Context Transfer: "AAPL" from the user input is passed to the sub-agent, clarifying the analysis target.

Confusing Parts:

finish_reason: "tool_calls" means the LLM finished responding with a tool call instead of generating text.
The reason arguments is in JSON string format ("{\"ticker\": \"AAPL\"}") is that it is the standard format for OpenAI API.
Why call only data_analyst? → Because the LLM read the prompt and selected a sequential approach.

Detailed Explanation of the arguments Field Generation Process: arguments: "{\"ticker\": \"AAPL\"}" was automatically generated by the LLM. The process is as follows:

Google ADK passes sub-agent information to the LLM:
- When registering AgentTool(agent=data_analyst) as a tool, Google ADK passes the data_analyst agent's description and name to the LLM.
- In code: data_analyst = LlmAgent(name="DataAnalyst", description="Gathers and analyzes basic stock market data...")
LLM analyzes User Input:
- User Input: "Give me investment advice for AAPL stock"
- The LLM recognizes "AAPL" as a stock ticker symbol.
LLM selects tool and generates parameters:
- The LLM reads "ANALYSIS METHODOLOGY" in the prompt and determines that data must be gathered first.
- It understands that the data_analyst tool collects stock data.
- It extracts "AAPL" from the user input to use as the ticker parameter.
- Google ADK automatically infers standard parameters like ticker or identifies necessary parameters based on the agent's description when calling sub-agents.
LLM generates arguments in JSON format:
- The LLM generates the parameters required for the function call in a JSON string format.
- ticker is recognized as a standard parameter meaning stock ticker symbol.
JSON
```
"arguments": "{\"ticker\": \"AAPL\"}"
```

Summary: arguments are not explicitly stated in the prompt but are automatically generated by the LLM by analyzing user input, referencing the description of available tools, and extracting necessary parameter values.

Interpretation:

LLM reads the prompt and understands the analysis process.
Based on "ANALYSIS METHODOLOGY" in the PROMPT, it decides to collect basic data first.
It extracts "AAPL" from the user input to use as the ticker parameter.
Decides to call data_analyst sub-agent and generates arguments.

Step 2: Executing Data Analyst Sub-agent

2-1. Data Analyst Agent Initialization and LLM Call #2

Call Location: data_analyst agent in financial_advisor/sub_agents/data_analyst.py Request Sent from Google ADK → OpenAI GPT-4o API:

JSON

{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "You are a Data Analyst who gathers stock information using 4 specialized tools:\n\n1. **get_company_info(ticker)** - Learn about the company...\n2. **get_stock_price(ticker, period)** - Get current pricing...\n3. **get_financial_metrics(ticker)** - Check key financial ratios..."
    },
    {
      "role": "user",
      "content": "Analyze ticker: AAPL"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_company_info",
        "description": "Retrieves basic company information for a given stock ticker..."
      }
    },
    {
      "type": "function",
      "function": {
        "name": "get_stock_price",
        "description": "Fetches historical stock price data..."
      }
    },
    {
      "type": "function",
      "function": {
        "name": "get_financial_metrics",
        "description": "Retrieves key financial metrics and valuation ratios..."
      }
    }
  ]
}

Generator: Google ADK (Data Analyst Sub-agent System) Receiver: OpenAI GPT-4o API

Role and Impact of this JSON: This JSON is the request where the Data Analyst sub-agent calls its own dedicated LLM upon initial activation.

Role in the Overall Process:

Sub-agent Activation: The Data Analyst starts working independently after receiving delegation from the Main Agent.
Specialization: Provides only the Data Analyst-specific prompt and tools, ensuring focus solely on data collection.
Domain Separation: Unlike the Main Agent's complex prompt, this provides simple and clear data collection instructions.

What happens via this JSON:

The Data Analyst-dedicated LLM instance is activated (separate from the Main Agent).
The LLM understands the Data Analyst role and grasps the functions of the 3 tools.
The LLM receives the task instruction "Analyze AAPL".
The LLM is ready to decide the next step (which tool to call).

Impact:

Expertise: The Main Agent doesn't need to do everything; it delegates to an agent specialized in data collection.
Work Distribution: Reduces the burden on the Main Agent, allowing each sub-agent to focus on its area of expertise.
Scalability: Adding new data collection tools only requires modifying this agent.

Confusing Parts:

user.content: "Analyze ticker: AAPL" is the natural language conversion of the ticker: "AAPL" parameter passed by the Main Agent.
system.content is the content specified in the instruction parameter when defining the data_analyst agent (different from the Main Agent's prompt).
description in the tools array is automatically parsed from the Python function's docstring.

Response received by Google ADK from OpenAI GPT-4o API (LLM Response #2):

JSON

{
  "tool_calls": [
    {
      "id": "call_456",
      "type": "function",
      "function": {
        "name": "get_company_info",
        "arguments": "{\"ticker\": \"AAPL\"}"
      }
    },
    {
      "id": "call_457",
      "type": "function",
      "function": {
        "name": "get_stock_price",
        "arguments": "{\"ticker\": \"AAPL\", \"period\": \"1y\"}"
      }
    },
    {
      "id": "call_458",
      "type": "function",
      "function": {
        "name": "get_financial_metrics",
        "arguments": "{\"ticker\": \"AAPL\"}"
      }
    }
  ]
}

Generator: OpenAI GPT-4o LLM (for Data Analyst Agent) Receiver: Google ADK (Data Analyst Sub-agent System)

Role and Impact of this JSON: This JSON is the result of the Data Analyst LLM deciding to collect all 3 required data points.

Role in the Overall Process:

Tool Call Decision: The LLM determines that company_info, stock_price, and financial_metrics are all needed.
Parallel Execution Instruction: Calls multiple tools at once for efficient data collection.
Parameter Decision: Determines parameter values to pass to each tool (ticker: "AAPL", period: "1y", etc.).

What happens via this JSON:

Google ADK parses the tool_calls array and recognizes 3 tool calls.
Google ADK executes each tool in parallel (improving efficiency).
Each Python function (get_company_info, get_stock_price, get_financial_metrics) calls the Yahoo Finance API.
Actual data is collected and returned to Google ADK.

Impact:

Efficiency: Parallel calls reduce time compared to sequential calls.
Data Completeness: The LLM decides to collect all necessary data at once, preventing incomplete analysis.
Parameter Optimization: The LLM selecting period: "1y" indicates it judged this as an appropriate period for analysis.

Confusing Parts:

Why call 3 at the same time? → Because the LLM judged that all 3 pieces of information are needed (influenced by instruction).
How was period: "1y" decided? → The LLM looked at the function docstring explanation ("1y: 1 year") and judged it suitable for general analysis.
Is sequential calling possible? → Yes, but in this case, the LLM judged parallel calling to be more efficient.

Interpretation:

Data Analyst LLM decided to call 3 tools simultaneously (parallel execution).
Each tool is executed as an actual Python function.

2-2. Actual Tool Function Execution (No LLM Call, Direct Execution)

Function Execution 1: get_company_info("AAPL")

Python

# Actual API call using yfinance library
stock = yf.Ticker("AAPL")
info = stock.info  # Yahoo Finance API call occurs
# Return Value (Python Function → Returned to Google ADK)
{
  "ticker": "AAPL",
  "success": True,
  "company_name": "Apple Inc.",
  "industry": "Consumer Electronics",
  "sector": "Technology"
}

Generator: Python function get_company_info (Receiving data from Yahoo Finance API) Receiver: Google ADK (Data Analyst Sub-agent System)

Function Execution 2: get_stock_price("AAPL", "1y")

Python

stock = yf.Ticker("AAPL")
history = stock.history(period="1y")  # Requesting 1 year of price data
# Return Value (Python Function → Returned to Google ADK)
{
  "ticker": "AAPL",
  "success": True,
  "history": "{\"Open\": {...}, \"High\": {...}, \"Low\": {...}, \"Close\": {...}, \"Volume\": {...}}",
  "current_price": 175.43
}

Generator: Python function get_stock_price (Receiving data from Yahoo Finance API) Receiver: Google ADK (Data Analyst Sub-agent System)

Function Execution 3: get_financial_metrics("AAPL")

Python

stock = yf.Ticker("AAPL")
info = stock.info
# Return Value (Python Function → Returned to Google ADK)
{
  "ticker": "AAPL",
  "success": True,
  "market_cap": 2700000000000,  # 2.7 Trillion USD
  "pe_ratio": 28.5,
  "dividend_yield": 0.0052,  # 0.52%
  "beta": 1.23
}

Generator: Python function get_financial_metrics (Receiving data from Yahoo Finance API) Receiver: Google ADK (Data Analyst Sub-agent System)

2-3. Data Analyst LLM Call #3 (Result Analysis)

Request Sent from Google ADK → OpenAI GPT-4o API (Previous conversation + Tool execution results):

JSON

{
  "messages": [
    {
      "role": "system",
      "content": "You are a Data Analyst..."
    },
    {
      "role": "user",
      "content": "Analyze ticker: AAPL"
    },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [...]
    },
    {
      "role": "tool",
      "content": "{\"ticker\": \"AAPL\", \"success\": true, \"company_name\": \"Apple Inc.\", ...}"
    },
    {
      "role": "tool",
      "content": "{\"ticker\": \"AAPL\", \"success\": true, \"history\": \"{...}\", \"current_price\": 175.43}"
    },
    {
      "role": "tool",
      "content": "{\"ticker\": \"AAPL\", \"success\": true, \"market_cap\": 2700000000000, ...}"
    }
  ]
}

Generator: Google ADK (Data Analyst Sub-agent System - Includes previous chat history and tool execution results) Receiver: OpenAI GPT-4o API

Role and Impact of this JSON: This JSON is a request for the Data Analyst to analyze the collected raw data and convert it into meaningful text.

Role in the Overall Process:

Maintaining Conversation History: Includes previous requests (user) and responses (assistant's tool_calls) so the LLM understands context.
Data Delivery: Provides the LLM with the actual data (JSON) collected from the 3 tools.
Analysis Task Instruction: Requests the LLM to "analyze this data and convert it into text the user can understand."

What happens via this JSON:

The LLM checks the tools it previously called (tool_calls) and their results (tool messages).
The LLM comprehensively analyzes the collected data (company info, stock price, financial metrics).
The LLM interprets the raw data and generates structured analysis text.
The generated text is returned to Google ADK and automatically saved to the state based on the output_key setting.

Impact:

Data → Insight Conversion: Converts raw JSON data into a human-readable analysis report.
State Storage: The analysis result is saved in state["data_analyst_result"], making it available for the Main Agent later.
Process Progression: The Data Analyst's task is complete, allowing the Main Agent to proceed to the next step (calling Financial Analyst).

Confusing Parts:

The role: "tool" message is the way tool function return values are passed to the LLM (OpenAI API standard format).
Reason content is a JSON string: The dictionary returned by the tool function is serialized into JSON.
Why call the LLM again? → Raw data has no meaning on its own; the LLM must interpret it to derive insights.

Response received by Google ADK from OpenAI GPT-4o API (LLM Response #3 - Final Analysis Text):

"**Company Overview:**
Apple Inc. is a technology company in the Consumer Electronics industry...
**Current Pricing:**
Current price: $175.43
Market Cap: $2.7 trillion
P/E Ratio: 28.5 (indicating premium valuation)
1-year price range: $164.08 - $198.23
**Financial Metrics:**
Dividend Yield: 0.52% (moderate income component)
Beta: 1.23 (slightly more volatile than market)"

Generator: OpenAI GPT-4o LLM (for Data Analyst Agent) Receiver: Google ADK State Storage: Google ADK automatically saves to state["data_analyst_result"] according to output_key="data_analyst_result" setting

Role and Impact of this JSON (Text Response): This text is the final output of the Data Analyst sub-agent, the result of analyzing the raw data.

Role in the Overall Process:

Analysis Result Output: Generates structured analysis text by interpreting collected data.
State Storage: Automatically saved to state according to output_key setting, making it usable by other agents.
Task Completion Signal: The Data Analyst's task is complete, and control is returned to the Main Agent.

What happens via this text:

Google ADK receives this text and checks the output_key="data_analyst_result" setting.
Google ADK automatically saves state["data_analyst_result"] = "Text Content".
The Data Analyst sub-agent's task is finished.
The Main Agent sees this result and decides the next step (calling Financial Analyst).

Impact:

Data Sharing: Saved in state so the Main Agent and other functions (save_advice_report) can access it.
Process Chain: The Main Agent looks at this result to decide whether to call the next sub-agent.
Final Report Composition: Later, the save_advice_report function will include this text to create the comprehensive report.

Confusing Parts:

Why is it in text format? → LLM output is always text, and state can only store strings.
Why is it automatically saved to State? → Because the output_key parameter is set (Code: data_analyst = LlmAgent(..., output_key="data_analyst_result")).
How is this text passed to the Main Agent? → Indirectly via State (The Main Agent reads from the state).

Step 5: Main Agent's Final Analysis and Advice

5-1. Main Agent LLM Call #10 (Comprehensive Analysis)

Request Sent from Google ADK → OpenAI GPT-4o API:

JSON

{
  "messages": [
    {
      "role": "system",
      "content": "[PROMPT content - including asking for user preferences]"
    },
    {
      "role": "user",
      "content": "Give me investment advice for AAPL stock"
    },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [{"name": "data_analyst", ...}]
    },
    {
      "role": "tool",
      "content": "[data_analyst result]"
    },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [{"name": "financial_analyst", ...}]
    },
    {
      "role": "tool",
      "content": "[financial_analyst result]"
    },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [{"name": "news_analyst", ...}]
    },
    {
      "role": "tool",
      "content": "[news_analyst result]"
    }
  ]
}

Generator: Google ADK (Main Agent System - Includes results from all sub-agents) Receiver: OpenAI GPT-4o API

Role and Impact of this JSON: This JSON represents the stage where the Main Agent synthesizes the analysis results from all sub-agents before generating the final advice.

Role in the Overall Process:

Conversation History Accumulation: Full conversation record from user request to all sub-agent calls and results.
Context Integration: Enables comprehensive judgment by including results from Data Analyst, Financial Analyst, and News Analyst.
Preparation for Final Decision: Preparation to generate advice tailored to the user based on all analysis data.

What happens via this JSON:

The LLM reviews the entire conversation history to understand the situation.
The LLM checks the analysis results of all 3 sub-agents.
The LLM checks "INVESTMENT RECOMMENDATION PROCESS" in the prompt.
The LLM determines that user preferences (investment goal, risk tolerance, time horizon) are needed.
The LLM generates text to ask the user.

Impact:

Tailored Advice: By asking for user preferences first, personalized investment advice can be provided.
Process Delay: The process is paused as it must wait for the user's additional response.
Conversational Interaction: Provides a personalized service through dialogue rather than simple one-way advice.

Confusing Parts:

[data_analyst result] in the role: "tool" message is the return value of the sub-agent call, not the value read from the state.
Why ask the user at this point? → Because there is an instruction in the prompt: "Before providing any BUY/SELL/HOLD recommendation, you MUST: Ask about..."
Reason for including all sub-agent results: The LLM needs all information to make a comprehensive judgment.

Response received by Google ADK from OpenAI GPT-4o API (LLM Response #10 - User Preference Question):

"Before providing investment advice, I need some information:
1. **Investment Goal**: Do you want growth investing, income investing, or short-term trading?
2. **Risk Tolerance**: Do you have a conservative, neutral, or aggressive investment preference?
3. **Time Horizon**: Short-term (under 1 year), Medium-term (1-3 years), or Long-term (over 3 years)?
If you provide this information, I will provide a tailored investment recommendation for AAPL."

Generator: OpenAI GPT-4o LLM (for Main Agent) Receiver: Google ADK → Displayed to User

5-2. User Response (Example)

"Investment Goal: Growth Investing
Risk Tolerance: Neutral
Time Horizon: Long-term (over 3 years)"

5-3. Main Agent LLM Call #11 (Final Advice Generation)

Request Sent from Google ADK → OpenAI GPT-4o API (Including User Response):

JSON

{
  "messages": [
    ... (Entire previous conversation),
    {
      "role": "user",
      "content": "Investment Goal: Growth Investing\nRisk Tolerance: Neutral\nTime Horizon: Long-term (over 3 years)"
    }
  ]
}

Generator: Google ADK (Main Agent System - User response added) Receiver: OpenAI GPT-4o API

Role and Impact of this JSON: This JSON is the request to generate the final investment advice by adding the user's preference information.

Role in the Overall Process:

User Input Addition: Adds the preference information provided by the user to the conversation history.
Preparation for Comprehensive Judgment: Preparation to generate final advice based on all analysis data (sub-agent results) + user preferences.
Process Completion Phase: Generating the final output with all information collected.

What happens via this JSON:

The LLM checks the user's preference information (Growth, Neutral, Long-term).
The LLM synthesizes the analysis results of the 3 sub-agents and the user preferences.
The LLM decides BUY/SELL/HOLD according to "RECOMMENDATION REQUIREMENTS" in the prompt.
The LLM generates specific advice text (including strengths, risk factors, target price, etc.).

Impact:

Final Output Generation: The investment advice, the core purpose of the system, is completed.
Tailored Result: Provides personalized advice tailored to the user's preferences.
Process Completion: Major analysis tasks are completed, and the result is provided to the user.

Confusing Parts:

... (Entire previous conversation) actually includes hundreds of lines of conversation history (abbreviated here).
Why is the entire previous conversation needed? → So the LLM can understand the context and generate a consistent response.
Reason user response is added as role: "user": To maintain the continuity of the conversation.

Response received by Google ADK from OpenAI GPT-4o API (LLM Response #11 - Final Investment Advice):

"**AAPL (Apple Inc.) Investment Recommendation: BUY**
**Comprehensive Analysis Summary:**
**Strengths:**
- Strong Financial Health: Free Cash Flow $99.6B, Good Debt Ratio
- Stable Profitability: Operating Margin 30.2%, Net Income $97B
- Services Segment Growth: 15% YoY increase
- Premium Valuation: P/E 28.5 (Reflecting growth expectations)
**Risk Factors:**
- Exposure to the Chinese market
- Potential short-term volatility due to premium valuation
**Investment Recommendation (Neutral Risk, Long-term Growth):**
BUY - Target Price: $210 (12 months)
AAPL is suitable for long-term growth investment. Strong financial health and growth in the services sector are expected to continue."

Generator: OpenAI GPT-4o LLM (for Main Agent) Receiver: Google ADK → Displayed to User

Google ADK: Financial Advisor(2)- full code

hyunsoo CHUNG — Sat, 3 Jan 2026 02:43:00 +0900

agent.py

from google.genai import types

from google.adk.tools import ToolContext

from google.adk.agents import Agent

from google.adk.tools.agent_tool import AgentTool

from google.adk.models.lite_llm import LiteLlm

from .sub_agents.data_analyst import data_analyst

from .sub_agents.financial_analyst import financial_analyst

from .sub_agents.news_analyst import news_analyst

from .prompt import PROMPT

MODEL = LiteLlm("openai/gpt-4o")

async def save_advice_report(tool_context: ToolContext, summary: str, ticker: str):

state = tool_context.state

data_analyst_result = state.get("data_analyst_result")

financial_analyst_result = state.get("financial_analyst_result")

news_analyst_analyst_result = state.get("news_analyst_analyst_result")

report = f"""

# Excetuve Summary and Advice:

{summary}

## Data Analyst Report:

{data_analyst_result}

## Financial Analyst Report:

{financial_analyst_result}

## News Analyst Report:

{news_analyst_analyst_result}

"""

state["report"] = report

filename = f"{ticker}_investment_advice.md"

artifact = types.Part(

inline_data=types.Blob(

mime_type="text/markdown",

data=report.encode("utf-8"),

)

await tool_context.save_artifact(filename, artifact)

return {

"success": True,

}

financial_advisor = Agent(

name="FinancialAdvisor",

instruction=PROMPT,

model=MODEL,

tools=[

AgentTool(agent=financial_analyst),

AgentTool(agent=news_analyst),

AgentTool(agent=data_analyst),

save_advice_report,

)

root_agent = financial_advisor

promt.py

PROMPT = """

You are a Professional Financial Advisor specializing in equity analysis and investment recommendations. You ONLY provide advice on stocks, trading, and investment decisions.

**STRICT SCOPE LIMITATIONS:**

- ONLY answer questions about stocks, trading, investments, financial markets, and company analysis

- REFUSE to answer questions about: general knowledge, technology help, personal advice unrelated to finance, or any non-financial topics

- If asked about non-financial topics, politely redirect: "I'm a specialized financial advisor. I can only help with stock analysis and investment decisions."

**INVESTMENT RECOMMENDATION PROCESS:**

Before providing any BUY/SELL/HOLD recommendation, you MUST:

1. Ask about the user's investment goals (growth, income, speculation, etc.)

2. Ask about their risk tolerance (conservative, moderate, aggressive)

3. Ask about their investment timeline (short-term, medium-term, long-term)

**RECOMMENDATION REQUIREMENTS:**

After gathering user preferences, you MUST provide a clear recommendation:

- **BUY**: Strong positive outlook with specific price targets and rationale

- **SELL**: Negative outlook with clear reasons to exit

- **HOLD**: Neutral position with conditions for future action

**Available Specialized Tools:**

- **data_analyst**: Gathers market data, company info, pricing, and financial metrics

- **news_analyst**: Searches current news and industry information using web tools

- **financial_analyst**: Analyzes detailed financial statements including income, balance sheet, and cash flow

**Direct Tools:**

- **save_company_report()**: Save comprehensive reports as artifacts (use ONLY when user requests a report and you have all the data you need for it.)

**ANALYSIS METHODOLOGY:**

For thorough analysis, you should:

1. Gather quantitative data (financial metrics, performance, valuation)

2. Research current news and market sentiment

3. Analyze financial statements for fundamental strength

4. Consider user's specific goals and risk profile

5. Provide confident recommendation with clear reasoning

**REPORT REQUIREMENTS:**

When creating reports, include:

- Executive Summary with clear BUY/SELL/HOLD recommendation

- Fundamental Analysis (financial health, valuation metrics)

- Technical Analysis (price trends, momentum)

- News and Market Sentiment Analysis

- Risk Assessment specific to user's tolerance

- Price Targets and Timeline

- Action Plan with entry/exit strategies

**Communication Style:**

- Be confident and decisive in recommendations

- Use specific data points and metrics

- Explain reasoning clearly with supporting evidence

- Provide actionable investment guidance

- Show conviction in your analysis

You are an expert who makes money for clients through sound investment decisions. Be opinionated and confident.

"""

__init__.py

from . import agent

data_analyst.py

import yfinance as yf

from google.adk.agents import LlmAgent

from google.adk.models.lite_llm import LiteLlm

MODEL = LiteLlm(model="openai/gpt-4o")

def get_company_info(ticker: str) -> str:

"""

Retrieves basic company information for a given stock ticker.

This tool fetches fundamental company details including the official company name,

industry classification, and sector categorization from Yahoo Finance.

Args:

ticker (str): The stock ticker symbol (e.g., 'AAPL' for Apple Inc.)

Returns:

dict: A dictionary containing:

- ticker (str): The input ticker symbol

- success (bool): True if the operation was successful

- company_name (str): Full legal name of the company

- industry (str): Specific industry classification

- sector (str): Broader sector categorization

Example:

>>> get_company_info('MSFT')

{

'ticker': 'MSFT',

'success': True,

'company_name': 'Microsoft Corporation',

'industry': 'Software - Infrastructure',

'sector': 'Technology'

}

"""

stock = yf.Ticker(ticker)

info = stock.info

return {

"ticker": ticker,

"success": True,

"company_name": info.get("longName", "NA"),

"industry": info.get("industry", "NA"),

"sector": info.get("sector", "NA"),

}

def get_stock_price(ticker: str, period: str) -> str:

"""

Fetches historical stock price data and current trading price for a given ticker.

This tool retrieves both the current market price and historical price data

over a specified time period, including open, high, low, close prices and volume.

Args:

ticker (str): Stock ticker symbol (e.g., 'AAPL' for Apple Inc.)

period (str): Time period for historical data. Valid options:

- '1d': 1 day

- '5d': 5 days

- '1mo': 1 month (default)

- '3mo': 3 months

- '6mo': 6 months

- '1y': 1 year

- '2y': 2 years

- '5y': 5 years

- '10y': 10 years

- 'ytd': Year to date

- 'max': Maximum available data

Returns:

dict: A dictionary containing:

- ticker (str): The input ticker symbol

- success (bool): True if the operation was successful

- history (str): JSON-formatted historical price data with OHLCV

- current_price (float): Current market price of the stock

Example:

>>> get_stock_price('TSLA', '3mo')

{

'ticker': 'TSLA',

'success': True,

'history': '{"Open": {...}, "High": {...}, ...}',

'current_price': 245.67

}

"""

stock = yf.Ticker(ticker)

info = stock.info

history = stock.history(period=period)

return {

"ticker": ticker,

"success": True,

"history": history.to_json(),

"current_price": info.get("currentPrice"),

}

def get_financial_metrics(ticker: str) -> str:

"""

Retrieves key financial metrics and valuation ratios for stock analysis.

This tool fetches essential financial indicators that help assess a company's

valuation, profitability, dividend policy, and market risk characteristics.

Args:

ticker (str): Stock ticker symbol (e.g., 'AAPL' for Apple Inc.)

Returns:

dict: A dictionary containing:

- ticker (str): The input ticker symbol

- success (bool): True if the operation was successful

- market_cap (float): Total market capitalization in USD

- pe_ratio (float): Trailing Price-to-Earnings ratio (price/earnings per share)

- dividend_yield (float): Annual dividend yield as a percentage (0.02 = 2%)

- beta (float): Stock's beta coefficient measuring volatility vs market

Notes:

- Market Cap: Represents company's total value (shares * price)

- P/E Ratio: Lower may indicate undervalued; higher may indicate growth expectations

- Dividend Yield: Annual dividends as percentage of stock price

- Beta: <1 means less volatile than market; >1 means more volatile

Example:

>>> get_financial_metrics('JNJ')

{

'ticker': 'JNJ',

'success': True,

'market_cap': 385000000000,

'pe_ratio': 15.2,

'dividend_yield': 0.031,

'beta': 0.65

}

"""

stock = yf.Ticker(ticker)

info = stock.info

return {

"ticker": ticker,

"success": True,

"market_cap": info.get("marketCap", "NA"),

"pe_ratio": info.get("trailingPE", "NA"),

"dividend_yield": info.get("dividendYield", "NA"),

"beta": info.get("beta", "NA"),

}

data_analyst = LlmAgent(

name="DataAnalyst",

model=MODEL,

description="Gathers and analyzes basic stock market data using multiple focused tools",

instruction="""

You are a Data Analyst who gathers stock information using 4 specialized tools:

1. **get_company_info(ticker)** - Learn about the company (name, sector, industry)

2. **get_stock_price(ticker, period)** - Get current pricing and trading ranges

3. **get_financial_metrics(ticker)** - Check key financial ratios

Use multiple focused tools to gather different types of data.

Explain what each tool provides and present the information clearly.

""",

tools=[

get_company_info,

get_stock_price,

get_financial_metrics,

output_key="data_analyst_result",

)

financial_analyst.py

import yfinance as yf

from google.adk.agents import Agent

from google.adk.models.lite_llm import LiteLlm

MODEL = LiteLlm(model="openai/gpt-4o")

def get_income_statement(ticker: str):

"""

Retrieves the income statement for comprehensive revenue and profitability analysis.

This tool fetches detailed income statement data showing a company's financial

performance over recent reporting periods, including revenues, expenses, and

profit margins at various levels.

Args:

ticker (str): Stock ticker symbol (e.g., 'AAPL' for Apple Inc.)

Returns:

dict: A dictionary containing:

- ticker (str): The input ticker symbol

- success (bool): True if the operation was successful

- income_statement (str): JSON-formatted income statement data including:

* Total Revenue

* Cost of Revenue

* Gross Profit

* Operating Expenses

* Operating Income

* EBITDA

* Net Income

* Earnings Per Share (EPS)

Notes:

- Data typically covers the last 4 quarters and annual periods

- All financial figures are in the company's reporting currency

- Useful for analyzing revenue growth, margin trends, and profitability

Example:

>>> get_income_statement('GOOGL')

{

'ticker': 'GOOGL',

'success': True,

'income_statement': '{"Total Revenue": {...}, "Net Income": {...}}'

}

"""

stock = yf.Ticker(ticker)

# return stock.income_stmt.to_json()

return {

"ticker": ticker,

"success": True,

"income_statement": stock.income_stmt.to_json(),

}

def get_balance_sheet(ticker: str):

"""

Retrieves the balance sheet for analyzing financial position and capital structure.

This tool fetches comprehensive balance sheet data showing a company's assets,

liabilities, and shareholders' equity at specific points in time, providing

insight into financial health and capital efficiency.

Args:

ticker (str): Stock ticker symbol (e.g., 'AAPL' for Apple Inc.)

Returns:

dict: A dictionary containing:

- ticker (str): The input ticker symbol

- success (bool): True if the operation was successful

- balance_sheet (str): JSON-formatted balance sheet data including:

* Current Assets (cash, receivables, inventory)

* Non-Current Assets (PP&E, intangibles, investments)

* Current Liabilities (payables, short-term debt)

* Non-Current Liabilities (long-term debt, deferred items)

* Total Shareholders' Equity

* Working Capital components

Notes:

- Provides snapshot of financial position at quarter/year end

- Essential for calculating liquidity ratios (current ratio, quick ratio)

- Used to assess debt levels, asset efficiency, and book value

- All values in company's reporting currency

Example:

>>> get_balance_sheet('AMZN')

{

'ticker': 'AMZN',

'success': True,

'balance_sheet': '{"Total Assets": {...}, "Total Liabilities": {...}}'

}

"""

stock = yf.Ticker(ticker)

# return stock.balance_sheet.to_json()

return {

"ticker": ticker,

"success": True,

"balance_sheet": stock.balance_sheet.to_json(),

}

def get_cash_flow(ticker: str):

"""

Retrieves the cash flow statement for analyzing cash generation and capital allocation.

This tool fetches detailed cash flow data showing how a company generates and

uses cash across operating, investing, and financing activities, crucial for

assessing financial sustainability and growth capacity.

Args:

ticker (str): Stock ticker symbol (e.g., 'AAPL' for Apple Inc.)

Returns:

dict: A dictionary containing:

- ticker (str): The input ticker symbol

- success (bool): True if the operation was successful

- cash_flow (str): JSON-formatted cash flow statement including:

* Operating Cash Flow (cash from core business)

* Capital Expenditures (CapEx)

* Free Cash Flow (Operating CF - CapEx)

* Investing Activities (acquisitions, investments)

* Financing Activities (debt, dividends, buybacks)

* Net Change in Cash

Notes:

- Operating cash flow indicates core business cash generation

- Free cash flow shows cash available for shareholders/growth

- Negative investing CF often indicates growth investment

- Financing CF reveals capital structure decisions

- Critical for assessing dividend sustainability and growth funding

Example:

>>> get_cash_flow('META')

{

'ticker': 'META',

'success': True,

'cash_flow': '{"Operating Cash Flow": {...}, "Free Cash Flow": {...}}'

}

"""

stock = yf.Ticker(ticker)

# return stock.balance_sheet.to_json()

return {

"ticker": ticker,

"success": True,

"cash_flow": stock.cash_flow.to_json(),

}

financial_analyst = Agent(

name="FinancialAnalyst",

model=MODEL,

description="Analyzes detailed financial statements including income, balance sheet, and cash flow",

instruction="""

You are a Financial Analyst who performs deep financial statement analysis. Your job:

1. **Income Analysis**: Use get_income_statement() to analyze revenue, profitability, and margins

2. **Balance Sheet Analysis**: Use get_balance_sheet() to examine assets, liabilities, and financial position

3. **Cash Flow Analysis**: Use get_cash_flow() to assess cash generation and capital allocation

**Your Financial Tools:**

- **get_income_statement(ticker)**: Revenue, profit margins, and profitability analysis

- **get_balance_sheet(ticker)**: Assets, debt, equity, and financial strength ratios

- **get_cash_flow(ticker)**: Operating cash flow, free cash flow, and capital expenditure

Analyze the financial health and performance of companies using comprehensive financial statement data.

Focus on key financial ratios, trends, and indicators that reveal the company's financial strength.

""",

tools=[

get_income_statement,

get_balance_sheet,

get_cash_flow,

output_key="financial_analyst_result",

)

news_analyst.py

from google.adk.agents import Agent

from google.adk.models.lite_llm import LiteLlm

from tools import web_search_tool

MODEL = LiteLlm(model="openai/gpt-4o")

news_analyst = Agent(

name="NewsAnalyst",

model=MODEL,

description="Uses Web Search tools to search and scrape real web content from the web.",

instruction="""

You are a News Analyst Specialist who uses web tools to find current information. Your job:

1. **Web Search**: Use web_search_tool() to find recent news about a company.

3. **Summarize Findings**: Explain what you found and its relevance

**Your Web Tools:**

- **web_search_tool()**: Firecrawl web search for company news

Use external APIs to search and scrape web content for current information.

""",

output_key="news_analyst_result",

tools=[

web_search_tool,

)

Google ADK: Financial Advisor(1)- setup

hyunsoo CHUNG — Sat, 3 Jan 2026 02:38:38 +0900

Now we learn about google adk.

By using this wonderful tool, you don't have to code frontend ui when your goal is just debugging and checking if code is alright as developer.

First of all, you set up files like this.

And pyproject.toml file is

[project]
name = "financial-analyst"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "firecrawl-py==2.16.3",
    "google-adk>=1.11.0",
    "google-genai>=1.31.0",
    "litellm>=1.75.8",
    "python-dotenv>=1.1.1",
    "yfinance>=0.2.65",
]

[dependency-groups]
dev = [
    "watchdog>=6.0.0",
]

then, you run uv sync in terminal at out folder(big project), not in inside folder.

then if you run terminl "uv run adk web" , you can recieve local page url.

OPEN AI SDK - Customer support agent(5) - Output_gaurdrail

hyunsoo CHUNG — Fri, 2 Jan 2026 02:40:53 +0900

1. Purpose and Concept of Output Guardrail

The Output Guardrail validates the response generated by the agent to check if it contains inappropriate content. Specifically, it ensures the Technical Support Agent does not include content unrelated to technical support (such as billing, orders, account management, etc.).

Core Concepts:

Automated Verification: Checks immediately after response generation.
Role Separation: Maintains strict role boundaries for the agent.
Blocking: Prevents inappropriate responses from reaching the user.

2. Data Model Definition

A. TechnicalOutputGuardRailOutput Model

class TechnicalOutputGuardRailOutput(BaseModel):

    contains_off_topic: bool
    contains_billing_data: bool
    contains_account_data: bool
    reason: str

Field Explanations:

contains_off_topic: Whether the response contains off-topic content.
contains_billing_data: Whether the response contains billing-related content.
contains_account_data: Whether the response contains account management-related content.
reason: The reason for the validation result.

3. Guardrail Agent Definition

A. technical_output_guardrail_agent

technical_output_guardrail_agent = Agent(
    name="Technical Support Guardrail",
    instructions="""
    Analyze the technical support response to check if it inappropriately contains:
    
    - Billing information (payments, refunds, charges, subscriptions)
    - Order information (shipping, tracking, delivery, returns)
    - Account management info (passwords, email changes, account settings)
    
    Technical agents should ONLY provide technical troubleshooting, diagnostics, and product support.
    Return true for any field that contains inappropriate content for a technical support response.
    """,
    output_type=TechnicalOutputGuardRailOutput,
)

Role:

Analyzes the response from the Technical Support Agent.
Inspects for inappropriate content.
Returns the result in the form of TechnicalOutputGuardRailOutput.

4. Output Guardrail Function Definition

A. @output_guardrail Decorator

@output_guardrail
async def technical_output_guardrail(
    wrapper: RunContextWrapper[UserAccountContext],
    agent: Agent,
    output: str,
):
    result = await Runner.run(
        technical_output_guardrail_agent,
        output,
        context=wrapper.context,
    )

    validation = result.final_output

    triggered = (
        validation.contains_off_topic
        or validation.contains_billing_data
        or validation.contains_account_data
    )

    return GuardrailFunctionOutput(
        output_info=validation,
        tripwire_triggered=triggered,
    )

Step-by-Step Explanation:

Function Signature
- @output_guardrail: Registers the function as an output guardrail.
- agent: The agent that generated the response.
- output: The response text to be validated.

@output_guardrail
async def technical_output_guardrail(..., output: str):

Execution of Guardrail Agent
- The technical_output_guardrail_agent analyzes the output.
- Passes the context.

result = await Runner.run(technical_output_guardrail_agent, output, ...)

Extraction of Validation Results

validation is an instance of TechnicalOutputGuardRailOutput.

TechnicalOutputGuardRailOutput(
    contains_billing_data=True,  # Issue found!
    reason="Response contains billing information..."
)

```
validation = result.final_output
```
Tripwire Decision
- If any condition is True, then triggered = True.
- Uses OR logic to handle complex conditions.

triggered = (validation.contains_off_topic or ...)

Return GuardrailFunctionOutput

return GuardrailFunctionOutput(
    output_info=validation,       # Detailed info
    tripwire_triggered=triggered, # True or False
)

5. GuardrailFunctionOutput Structure

GuardrailFunctionOutput is the standard return type for Guardrail functions.

Structure:

GuardrailFunctionOutput(
    output_info: BaseModel,      # Detailed validation info
    tripwire_triggered: bool      # Whether the Tripwire was triggered
)

Field Explanations:

output_info: Detailed information about the validation result (Pydantic model).
- Example: Instance of TechnicalOutputGuardRailOutput.
- The reason field explains the failure.
tripwire_triggered: Guardrail violation status (boolean).
- True: Guardrail violated, exception raised.
- False: Normal, processing continues.

6. Registering Guardrail to Technical Agent

technical_agent = Agent(
    name="Technical Support Agent",
    # ...
    output_guardrails=[
        technical_output_guardrail,
    ],
)

output_guardrails: A list of guardrails to execute after response generation.
Registers technical_output_guardrail.
Automatically executes after the agent generates a response.

7. Exception Handling

        except OutputGuardrailTripwireTriggered:
            st.write("Cant show you that answer.")
            st.session_state["text_placeholder"].empty()

When OutputGuardrailTripwireTriggered occurs:
- The response is judged as inappropriate.
- Displays "Cant show you that answer."
- Clears the existing response placeholder.

8. Full Execution Flow

Scenario 1: Normal Response (No Tripwire)

[Step 1] User Request
   User: "The app isn't working"
   ↓
[Step 2] Technical Agent Execution
   Runner.run_streamed(technical_agent, ...)
   → LLM Generates Response: "To fix the app issue, try these steps..."
   ↓
[Step 3] Output Guardrail Auto-Execution
   Runner checks technical_agent.output_guardrails
   → Calls technical_output_guardrail()
   ↓
[Step 4] Guardrail Agent Execution
   Runner.run(technical_output_guardrail_agent, output, ...)
   → LLM Analyzes response
   → Generates TechnicalOutputGuardRailOutput:
     {
       "contains_off_topic": false,
       "contains_billing_data": false,
       "reason": "Response contains only technical troubleshooting..."
     }
   ↓
[Step 5] Tripwire Decision
   triggered = false || false || false = false
   → Tripwire NOT triggered
   ↓
[Step 6] Return GuardrailFunctionOutput
   { tripwire_triggered: false }
   ↓
[Step 7] Runner Processing
   tripwire_triggered == False
   → No Exception
   → Display Response ✅

Scenario 2: Inappropriate Response (Tripwire Triggered)

[Step 1] User Request
   User: "The app isn't working"
   ↓
[Step 2] Technical Agent Generates Inappropriate Response
   LLM Generates: "To fix the app... Also, I checked your billing info..."
   ↓
[Step 3] Output Guardrail Auto-Execution
   Calls technical_output_guardrail()
   ↓
[Step 4] Guardrail Agent Execution
   LLM Analyzes response
   → Generates TechnicalOutputGuardRailOutput:
     {
       "contains_billing_data": true,  ← Issue Found!
       "reason": "Response contains billing information..."
     }
   ↓
[Step 5] Tripwire Decision
   triggered = false || true || false = true
   → Tripwire Triggered!
   ↓
[Step 6] Return GuardrailFunctionOutput
   { tripwire_triggered: true }
   ↓
[Step 7] Runner Processing
   tripwire_triggered == True
   → OutputGuardrailTripwireTriggered Exception Raised
   ↓
[Step 8] Exception Handling (main.py)
   except OutputGuardrailTripwireTriggered:
       st.write("Cant show you that answer.")
   → Inappropriate response is hidden from user ❌

9. Comparison: Input Guardrail vs Output Guardrail

Feature	Input Guardrail	Output Guardrail
Execution Time	After user input, before agent execution	After agent generates response
Validation Target	User Request	Agent Response
Purpose	Block inappropriate requests	Block inappropriate responses
Decorator	@input_guardrail	@output_guardrail
Parameter	input: str	output: str
Exception	InputGuardrailTripwireTriggered	OutputGuardrailTripwireTriggered
Guardrail Agent	input_guardrail_agent	technical_output_guardrail_agent
Output Type	InputGuardRailOutput	TechnicalOutputGuardRailOutput
Tripwire Decision	Single field (is_off_topic)	Complex conditions (OR logic)

10. Summary of Core Components

Component	Role	Location
TechnicalOutputGuardRailOutput	Data model for validation results	models.py
technical_output_guardrail_agent	Agent that analyzes the response	my_agents/technical_agent.py
@output_guardrail	Decorator for Guardrail functions	agents package
technical_output_guardrail	The Guardrail function itself	my_agents/technical_agent.py
GuardrailFunctionOutput	Return type for Guardrail functions	agents package
output_guardrails	List of Guardrails registered to an Agent	technical_agent definition
OutputGuardrailTripwireTriggered	Exception raised when Tripwire is triggered	agents package

11. Full System Diagram

┌─────────────────────────────────────────┐
│  User Request                           │
│  "The app isn't working"                │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Runner.run_streamed(technical_agent)   │
│  - Execute Technical Agent              │
│  - LLM Generates Response               │
│  - Response: "To fix the app..."        │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Output Guardrail Auto-Execution        │
│  Runner checks output_guardrails        │
│  → Calls technical_output_guardrail()   │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  technical_output_guardrail() Runs      │
│  - Execute Guardrail Agent              │
│  - Analyze Response Text                │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Guardrail Agent Execution              │
│  Runner.run(technical_output_guardrail_agent) │
│  - LLM analyzes response                │
│  - Checks for inappropriate content     │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Generate Validation Result             │
│  TechnicalOutputGuardRailOutput:        │
│  {                                      │
│    contains_off_topic: false,           │
│    contains_billing_data: false,        │
│    reason: "Response contains only..."  │
│  }                                      │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Tripwire Decision                      │
│  triggered = false || false || false    │
│  = false                                │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Return GuardrailFunctionOutput         │
│  {                                      │
│    output_info: TechnicalOutput...(),   │
│    tripwire_triggered: false            │
│  }                                      │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Runner Processing                      │
│  if tripwire_triggered == False:        │
│    → No Exception                       │
│    → Display Response ✅                │
│  else:                                  │
│    → OutputGuardrailTripwireTriggered   │
│    → "Cant show you that answer." ❌    │
└─────────────────────────────────────────┘

OPEN AI SDK - Customer support agent(4)- tools

hyunsoo CHUNG — Thu, 1 Jan 2026 21:02:53 +0900

Tool System Integration Explanation

1. Tool Definition - @function_tool Decorator

@function_tool
def run_diagnostic_check(
    context: UserAccountContext, product_name: str, issue_description: str
) -> str:
    """
    Run a diagnostic check on the customer's product to identify potential issues.

    Args:
        product_name: Name of the product experiencing issues
        issue_description: Description of the problem
    """
    diagnostics = [
        "✅ Server connectivity: Normal",
        "✅ API endpoints: Responsive",
        "⚠️  Cache memory: 85% full (recommend clearing)",
        "✅ Database connections: Stable",
        "⚠️  Last update: 7 days ago (update available)",
    ]

    return f"  Diagnostic results for {product_name}:\n" + "\n".join(diagnostics)

@function_tool: A decorator that registers a function as a tool.
Key Features:
- The first parameter is context: UserAccountContext (automatically injected).
- The remaining parameters are provided by the LLM.
- The Docstring is used as the tool description.
- The return value is a string.

2. How the LLM Understands Tools

A. Tool Schema Generation The @function_tool decorator analyzes the function to generate a schema that the LLM can understand:

# Function Definition
@function_tool
def lookup_order_status(context: UserAccountContext, order_number: str) -> str:
    """
    Look up the current status and details of an order.
    Args:
        order_number: Customer's order number
    """

Generated Tool Schema (Internally):

{
  "name": "lookup_order_status",
  "description": "Look up the current status and details of an order.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_number": {
        "type": "string",
        "description": "Customer's order number"
      }
    },
    "required": ["order_number"]
  }
}

B. Providing the Tool List

order_agent = Agent(
    name="Order Management Agent",
    instructions=dynamic_order_agent_instructions,
    tools=[
        lookup_order_status,
        initiate_return_process,
        schedule_redelivery,
        expedite_shipping,
    ],
    hooks=AgentToolUsageLoggingHooks(),
)

tools: A list of tools available to the agent.
The Runner generates a schema for each tool and provides it to the LLM.
The LLM selects a tool by referencing this list and schema.

3. Context Automatic Injection Mechanism

A. Context Delivery Path

            stream = Runner.run_streamed(
                st.session_state["agent"],
                message,
                session=session,
                context=user_account_ctx,
            )

Pass context=user_account_ctx to Runner.run_streamed().
The Runner internally wraps and manages it using RunContextWrapper.

B. Context Injection During Tool Calls

@function_tool
def lookup_order_status(context: UserAccountContext, order_number: str) -> str:
    """
    Look up the current status and details of an order.

    Args:
        order_number: Customer's order number
    """
    statuses = ["processing", "shipped", "in_transit", "delivered"]
    # ... implementation details ...
    return f"""
  Order Status: {order_number}
  Shipping to: {context.email}
    """.strip()

If the first parameter is of type UserAccountContext, the Runner automatically injects it.
The LLM does not provide the context parameter.
Inside the tool, properties like context.email, context.customer_id, context.tier, etc., can be used.

4. Parameter Generation Process by LLM

A. User Request Analysis

User: "Check the status of order number ORD-123"

B. Tool Selection

LLM Analysis:

Request: "Check order status"

Check available tools: lookup_order_status, initiate_return_process, etc.

Selection: lookup_order_status

C. Tool Schema Analysis

LLM Checks Schema for lookup_order_status:

name: "lookup_order_status"

description: "Look up the current status and details of an order."

parameters: order_number (string, required)

context is ignored as it is automatically injected.

D. Parameter Extraction

LLM Extracts Parameters from Request: "Check the status of order number ORD-123" → order_number="ORD-123"

E. Tool Call Generation

LLM Generates Tool Call:

JSON

{
  "tool_name": "lookup_order_status",
  "parameters": {
    "order_number": "ORD-123"
  }
}

5. Full Tool Execution Flow

[Step 1] User Request
   User: "Check the status of order number ORD-123"
   ↓
[Step 2] Call Runner.run_streamed()
   Runner.run_streamed(
       order_agent,
       "...",
       context=user_account_ctx  ← Context Passed
   )
   ↓
[Step 3] Runner Generates Tool Schema
   Runner checks order_agent.tools list
   → Analyzes @function_tool decorators
   → Prepares tool list for LLM
   ↓
[Step 4] Order Agent's LLM Execution
   Information provided to LLM:
   - Instructions, Tools (Schema), Request, History
   ↓
[Step 5] LLM Selects Tool & Extracts Parameters
   - Tool: lookup_order_status
   - Parameter: order_number="ORD-123"
   ↓
[Step 6] LLM Generates Tool Call
   Output: { "function": { "name": "lookup_order_status", ... } }
   ↓
[Step 7] on_tool_start Hook Called
   Displays "  Order Management Agent starting tool..." in sidebar
   ↓
[Step 8] Runner Executes Tool
   Runner calls function:
   lookup_order_status(
       context=wrapper.context,  ← Auto Injected
       order_number="ORD-123"    ← Provided by LLM
   )
   ↓
[Step 9] Tool Function Logic Execution
   Inside lookup_order_status():
   - Use context.email, context.tier
   - Query order logic
   - Return result string
   ↓
[Step 10] on_tool_end Hook Called
   Displays tool result in sidebar
   ↓
[Step 11] LLM Delivers Result to User
   LLM receives tool result → Converts to friendly message
   → "Order ORD-123 is currently in transit..."

6. Handling Parameter Types

def lookup_order_status(context: UserAccountContext, order_number: str) -> str:

No default value → Required.
The LLM must extract this from the user request. If missing, it asks the user.

B. Optional Parameters (Default Values)

def lookup_billing_history(context: UserAccountContext, months_back: int = 6) -> str:

Default value = 6 exists → Optional.
If the LLM cannot extract it, the default value is used.

C. Multiple Parameters

def initiate_return_process(..., order_number: str, return_reason: str, items: str) -> str:

Extract multiple parameters from the user request.
The LLM maps each parameter accordingly.

7. Context Usage Examples

A. Reading Info from Context

  Shipping to: {context.email}

context.email: Customer Email
context.customer_id: Customer ID
context.tier: Customer Tier

B. Context-based Conditional Logic

processing_days = 3 if context.is_premium_customer() else 5

context.is_premium_customer(): Check if premium.
Premium customers get faster processing (3 days vs 5 days).

C. Context-based Access Control

if not context.is_premium_customer():
    return "❌ Expedited shipping upgrade requires Premium membership"

Feature available only to premium customers.
Check permissions via Context.

8. Tool Usage Logging - AgentHooks

class AgentToolUsageLoggingHooks(AgentHooks):
    async def on_tool_start(self, ...):
        # ... Log tool start ...

    async def on_tool_end(self, ...):
        # ... Log tool result ...

    async def on_handoff(self, ...):
        # ... Log handoff ...

AgentHooks: Lifecycle event hooks for the agent.
Major Methods:
- on_tool_start: Called when a tool starts execution.
- on_tool_end: Called when a tool completes execution (includes result).
- on_handoff: Called when a handoff occurs.
- on_start / on_end: Agent activation/completion.

9. Key Concepts Summary

Concept	Description
@function_tool	Decorator that registers a function as a tool.
context	UserAccountContext automatically injected as the first parameter.
Tool Schema	Metadata generated for the tool so the LLM can understand it.
tools	List of tools to register with the agent.
AgentHooks	Class that handles agent lifecycle events.
on_tool_start	Hook called when tool execution begins.
on_tool_end	Hook called when tool execution completes.

10. Full System Diagram

┌─────────────────────────────────────────┐
│  User Request                           │
│  "Check the status of order ORD-123"    │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Runner.run_streamed(order_agent, ...)  │
│  Pass context=user_account_ctx          │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Runner Generates Tool Schema           │
│  - Analyze @function_tool decorator     │
│  - Parse function signature             │
│  - Parse Docstring                      │
│  - Generate JSON Schema                 │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Provide Tool Info to LLM               │
│  - Agent instructions                   │
│  - Tool List (with Schema)              │
│  - User Request                         │
│  - Conversation History                 │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  LLM Selects Tool & Extracts Params     │
│  - Analyze User Request                 │
│  - Select appropriate Tool              │
│  - Check Tool Schema                    │
│  - Extract: order_number="ORD-123"      │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  LLM Generates Tool Call                │
│  {                                      │
│    "tool_calls": [{                     │
│      "function": {                      │
│        "name": "lookup_order_status",   │
│        "arguments": "{\"order_number\": \"ORD-123\"}" │
│      }                                  │
│    }]                                   │
│  }                                      │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Call on_tool_start Hook                │
│  - Display tool start in sidebar        │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Runner Executes Tool                   │
│  lookup_order_status(                   │
│    context=wrapper.context,  ← Auto     │
│    order_number="ORD-123"    ← From LLM │
│  )                                      │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Tool Function Execution                │
│  - Use context.email, id, tier          │
│  - Query order status                   │
│  - Return result string                 │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Call on_tool_end Hook                  │
│  - Display tool result in sidebar       │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  LLM Delivers Result to User            │
│  "Order ORD-123 is currently..."        │
└─────────────────────────────────────────┘

OPEN AI SDK - Customer support agent(3) - handoff

hyunsoo CHUNG — Thu, 1 Jan 2026 15:00:27 +0900

1. Handoff Data Model Definition

class HandoffData(BaseModel):
    to_agent_name: str
    issue_type: str
    issue_description: str
    reason: str

HandoffData: Pydantic model containing handoff information
Fields:
- to_agent_name: Name of the target agent to hand off to
- issue_type: Type of issue
- issue_description: Description of the issue
- reason: Reason for the handoff

2. Handoff Handler Function

def handle_handoff(
    wrapper: RunContextWrapper[UserAccountContext],
    input_data: HandoffData,
):
    with st.sidebar:
        st.write(
            f"""
            Handing off to {input_data.to_agent_name}
            Reason: {input_data.reason}
            Issue Type: {input_data.issue_type}
            Description: {input_data.issue_description}
        """
        )

handle_handoff: Callback function called when a handoff occurs
Parameters:
- wrapper: Execution context wrapper (access UserAccountContext via wrapper.context)
- input_data: HandoffData instance
Behavior: Displays handoff information in the sidebar

3. Handoff Factory Function

def make_handoff(agent):
    return handoff(
        agent=agent,
        on_handoff=handle_handoff,
        input_type=HandoffData, 
        input_filter=handoff_filters.remove_all_tools,
    )

make_handoff: Factory function that creates a Handoff object
Parameter:
- agent: Target agent to hand off to
Returns: Handoff object created by handoff()
Configuration:
- agent: Target agent
- on_handoff: Callback when handoff occurs (handle_handoff)
- input_type: Handoff data type (HandoffData)
- input_filter: Input filter (handoff_filters.remove_all_tools to remove tools)

4. Role of input_type

        input_type=HandoffData,

input_type=HandoffData: Triggers handoff when LLM output matches HandoffData format
Behavior:
1. Runner parses LLM output
2. Checks if it matches HandoffData structure
3. If it matches, executes handoff

5. Role of RECOMMENDED_PROMPT_PREFIX

    return f"""
    {RECOMMENDED_PROMPT_PREFIX}

RECOMMENDED_PROMPT_PREFIX: Prompt prefix that guides the LLM on how to perform handoffs
Content:
- How to output in HandoffData format when a handoff is needed
- How to fill to_agent_name, issue_type, issue_description, reason
- When to perform a handoff

6. Registering Handoff with Main Agent

triage_agent = Agent(
    name="Triage Agent",
    instructions=dynamic_triage_agent_instructions,
    input_guardrails=[
        off_topic_guardrail,
    ],
    handoffs=[
        make_handoff(technical_agent),
        make_handoff(billing_agent),
        make_handoff(account_agent),
        make_handoff(order_agent),
    ],
)

handoffs: List to register multiple handoffs
Registered agents:
- technical_agent: Technical support
- billing_agent: Billing/payment
- account_agent: Account management
- order_agent: Order management

7. Target Agent Example

def dynamic_order_agent_instructions(
    wrapper: RunContextWrapper[UserAccountContext],
    agent: Agent[UserAccountContext],
):
    return f"""
    You are an Order Management specialist helping {wrapper.context.name}.
    Customer tier: {wrapper.context.tier} {"(Premium Shipping)" if wrapper.context.tier != "basic" else ""}
    
    YOUR ROLE: Handle order status, shipping, returns, and delivery issues.
    
    ORDER MANAGEMENT PROCESS:
    1. Look up order details by order number
    2. Provide current status and tracking information
    3. Resolve shipping or delivery issues
    4. Process returns and exchanges
    5. Update shipping preferences if needed
    
    ORDER INFORMATION TO PROVIDE:
    - Current order status (processing, shipped, delivered)
    - Tracking numbers and carrier information
    - Expected delivery dates
    - Return/exchange options and policies
    
    RETURN POLICY:
    - 30-day return window for most items
    - Free returns for premium customers
    - Exchange options available
    - Refund processing time: 3-5 business days
    
    {"PREMIUM PERKS: Free expedited shipping and returns, priority processing." if wrapper.context.tier != "basic" else ""}
    """

order_agent = Agent(
    name="Order Management Agent",
    instructions=dynamic_order_agent_instructions,
)

Target agents also use Context
Generate personalized responses using wrapper.context.name, wrapper.context.tier, etc.

8. Complete Execution Flow (Detailed)

[Step 1] User Input
   User: "Check my order status"
   ↓
[Step 2] Call Runner.run_streamed()
   Runner.run_streamed(
       triage_agent,
       "Check my order status",
       session=session,
       context=user_account_ctx
   )
   ↓
[Step 3] Input Guardrail Validation
   off_topic_guardrail() executes
   → Not off-topic (passes)
   ↓
[Step 4] Triage Agent Execution Starts
   dynamic_triage_agent_instructions() called
   → Includes {RECOMMENDED_PROMPT_PREFIX}
   → Uses wrapper.context.name, tier
   → "The customer's name is nico."
   → "The customer's tier is basic."
   ↓
[Step 5] Triage Agent's LLM Execution
   LLM processes conversation
   → Analyzes issue: "Order-related inquiry"
   → Classifies: "ORDER MANAGEMENT"
   ↓
[Step 6A] Normal Response Case
   LLM responds with normal text
   → "I'll help you with that..."
   → input_type doesn't match
   → Handoff not triggered
   → Conversation continues
   ↓
[Step 6B] HandoffData Format Case
   LLM responds in HandoffData format:
   {
     "to_agent_name": "Order Management Agent",
     "issue_type": "ORDER MANAGEMENT",
     "issue_description": "Order status check request",
     "reason": "Route to order-related specialist agent"
   }
   ↓
[Step 7] Runner Detects HandoffData Format
   Runner parses LLM output
   → Detects HandoffData format
   → Checks triage_agent.handoffs list
   → Finds handoff with input_type=HandoffData
   → Finds handoff object matching "Order Management Agent"
   ↓
[Step 8] Handoff Validation and Preparation
   - input_type validation: Checks if output is HandoffData format
   - Applies input_filter: handoff_filters.remove_all_tools
     → Removes unnecessary tools
   - Verifies target agent: order_agent exists
   ↓
[Step 9] on_handoff Callback Called
   handle_handoff(wrapper, input_data) executes
   - wrapper: Current RunContextWrapper (includes context)
   - input_data: Parsed HandoffData instance
   → Displays handoff information in sidebar:
     "Handing off to Order Management Agent
      Reason: Route to order-related specialist agent
      Issue Type: ORDER MANAGEMENT
      Description: Order status check request"
   ↓
[Step 10] Context Wrapping Maintained
   Existing wrapper.context maintained as-is
   → user_account_ctx is passed through
   ↓
[Step 11] Recursive Execution to Target Agent
   Inside Runner.run_streamed():
   Runner.run_streamed(
       order_agent,              ← Target agent
       input_data.issue_description,  ← Issue description from Handoff data as input
       session=session,          ← Same session maintained
       context=wrapper.context,   ← Context passed
   )
   ↓
[Step 12] Order Agent Execution Starts
   - Creates new RunContextWrapper (uses same context)
   - Calls dynamic_order_agent_instructions(wrapper, agent)
   - Can access wrapper.context.name, tier, etc.
   - "You are an Order Management specialist helping nico."
   - "Customer tier: basic"
   ↓
[Step 13] Order Agent Processes
   Order Agent's LLM processes order status check
   → Context information continues to be available
   → Generates personalized response

9. Internal Transfer Mechanism

A. Handoff Detection Mechanism

Triage Agent LLM Output:
- "I'll connect you with our Order Management specialist..." + Structured output in HandoffData format
Inside Runner:
- Parses LLM output
- Checks if output_type is HandoffData
- Finds matching handoff from handoffs list

B. Context Passing Mechanism

Triage Agent Execution: context=user_account_ctx → wrapper.context = user_account_ctx
Handoff Occurs: handle_handoff(wrapper, input_data) → wrapper.context is maintained as-is
Order Agent Execution: Runner.run_streamed(order_agent, ..., context=wrapper.context) → Same context is passed
Inside Order Agent: dynamic_order_agent_instructions(wrapper, agent) → Can access wrapper.context.name, tier, etc.

C. Session Maintenance Mechanism

Triage Agent Execution: session=session (SQLiteSession)
Handoff Occurs: Same session object maintained
Order Agent Execution: session=session (same session)
Result: Conversation history is stored continuously. Conversations from both Triage Agent and Order Agent are recorded in the same session.

10. input_type vs output_type Comparison

A. output_type (Guardrail Agent)

input_guardrail_agent = Agent(
    # ...
    output_type=InputGuardRailOutput,
)

output_type: Forces the agent to always output in this format.
Restricts LLM to respond only in InputGuardRailOutput format.

B. input_type (Handoff)

        input_type=HandoffData,

input_type: Triggers handoff only when output is in this format.
Triage Agent can also output normal text.
If output is in HandoffData format, handoff is executed.

11. Input Filtering Process

        input_filter=handoff_filters.remove_all_tools,

input_filter: Filters input during handoff
remove_all_tools: Removes all tools
Effects:
- Tools from Triage Agent are not passed to Order Agent
- Order Agent uses only its own tools
- Clean transfer

12. Roles and Benefits of Handoff

Specialist Agent Routing: Routes issues to appropriate specialist agents
Context Maintenance: Customer information is maintained after handoff
Traceability: Displays handoff information in sidebar
Extensibility: Multiple agents can be registered
Filtering: Removes unnecessary tools with input_filter
Flexibility: Conditional handoff trigger with input_type

13. Key Concepts Summary

Concept	Description
HandoffData	Pydantic model containing handoff information
handoff()	Function that creates a Handoff object
on_handoff	Callback function called when handoff occurs
input_type	Output data type that triggers handoff
input_filter	Input filtering option during handoff
handoffs	List that connects handoffs to agent
RECOMMENDED_PROMPT_PREFIX	Prompt that guides LLM on how to perform handoffs

14. Complete System Integration Diagram

┌─────────────────────────────────────────┐
│  Runner.run_streamed(triage_agent, ...) │
│  context=user_account_ctx               │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Input Guardrail Validation             │
│  off_topic_guardrail()                  │
└──────────────┬──────────────────────────┘
               │ Passes
               ▼
┌─────────────────────────────────────────┐
│  Triage Agent Execution                 │
│  - Includes RECOMMENDED_PROMPT_PREFIX   │
│  - Uses wrapper.context.name, tier      │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  LLM Output Generation                  │
│  - Normal text or HandoffData format    │
└──────────────┬──────────────────────────┘
               │
        ┌──────┴──────┐
        │             │
        ▼             ▼
┌──────────────┐  ┌──────────────────────┐
│ Normal Text  │  │ HandoffData Format   │
│              │  │ {                    │
│ Continue     │  │   to_agent_name:     │
│ Conversation │  │   issue_type:        │
│              │  │   ...                │
│              │  │ }                    │
└──────────────┘  └──────┬───────────────┘
                         │
                         ▼
            ┌────────────────────────────┐
            │ Runner Detects HandoffData │
            │ - input_type matches       │
            │ - Checks handoffs list     │
            └──────────────┬─────────────┘
                           │
                           ▼
            ┌────────────────────────────┐
            │ Apply input_filter         │
            │ - remove_all_tools         │
            └──────────────┬─────────────┘
                           │
                           ▼
            ┌────────────────────────────┐
            │ Call on_handoff Callback   │
            │ handle_handoff(wrapper,    │
            │              input_data)   │
            │ - Display info in sidebar  │
            └──────────────┬─────────────┘
                           │
                           ▼
            ┌────────────────────────────┐
            │ Maintain Context           │
            │ Pass wrapper.context as-is │
            └──────────────┬─────────────┘
                           │
                           ▼
            ┌────────────────────────────┐
            │ Runner.run_streamed(       │
            │   order_agent,             │
            │   issue_description,       │
            │   context=wrapper.context  │
            │ )                          │
            │ (Recursive call)           │
            └──────────────┬─────────────┘
                           │
                           ▼
            ┌────────────────────────────┐
            │ Order Agent Execution      │
            │ - dynamic_order_agent_     │
            │   instructions()           │
            │ - Uses wrapper.context.name,│
            │   tier                     │
            │ - Processes order status   │
            │   check                    │
            └────────────────────────────┘

OPEN AI SDK - Customer support agent(2) - Inputgaurdrail & context

hyunsoo CHUNG — Tue, 30 Dec 2025 19:07:20 +0900

Context and Input Guardrail System

1. Context Model Definition

models.py Lines 5-9

class UserAccountContext(BaseModel):
    customer_id: int
    name: str
    tier: str = "basic"
    email: Optional[str] = None  # premium enterprise

UserAccountContext: Pydantic model containing customer account information
Fields:
- customer_id: Customer ID
- name: Customer name
- tier: Tier (default "basic", can be "premium", "enterprise")
- email: Email (optional)

2. Context Instance Creation and Passing

main.py Lines 13-17

user_account_ctx = UserAccountContext(
    customer_id=1,
    name="nico",
    tier="basic",
)

user_account_ctx: Creates a customer information instance

main.py Lines 53-58

            stream = Runner.run_streamed(
                triage_agent,
                message,
                session=session,
                context=user_account_ctx,
            )

Passes context=user_account_ctx to Runner.run_streamed()
This context is passed when the agent runs

3. Accessing Context via RunContextWrapper

A. Using Context in Guardrail Function

triage_agent.py Lines 20-35

@input_guardrail
async def off_topic_guardrail(
    wrapper: RunContextWrapper[UserAccountContext],
    agent: Agent[UserAccountContext],
    input: str,
):
    result = await Runner.run(
        input_guardrail_agent,
        input,
        context=wrapper.context,
    )

    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=result.final_output.is_off_topic,
    )

wrapper: RunContextWrapper[UserAccountContext]: Wrapper object for context
wrapper.context: Access to the actual UserAccountContext instance
The same context is passed to the guardrail agent (line 29)
you should use @input_gaurdrail decorater to registers this function as input guardrail.

B. Using Context in Dynamic Prompt

triage_agent.py Lines 38-48

def dynamic_triage_agent_instructions(
    wrapper: RunContextWrapper[UserAccountContext],
    agent: Agent[UserAccountContext],
):
    return f"""
    You are a customer support agent. You ONLY help customers with their questions about their User Account, Billing, Orders, or Technical Support.
    You call customers by their name.
    
    The customer's name is {wrapper.context.name}.
    The customer's email is {wrapper.context.email}.
    The customer's tier is {wrapper.context.tier}.

dynamic_triage_agent_instructions: Function called at runtime
Inserts customer information into the prompt using wrapper.context.name, wrapper.context.email, wrapper.context.tier
The prompt is generated based on context for each execution

4. Input Guardrail System

A. Guardrail Output Model

models.py Lines 12-15

class InputGuardRailOutput(BaseModel):

    is_off_topic: bool
    reason: str

InputGuardRailOutput: Model for guardrail validation results
is_off_topic: Whether the request is off-topic (True blocks the request)
reason: Reason for blocking

B. Guardrail Dedicated Agent

triage_agent.py Lines 10-18

input_guardrail_agent = Agent(
    name="Input Guardrail Agent",
    instructions="""
    Ensure the user's request specifically pertains to User Account details, Billing inquiries, Order information, or Technical Support issues, and is not off-topic. 
    If the request is off-topic, return a reason for the tripwire.You can make small conversation with the user, specially at the beginning of the conversation, 
    but don't help with requests that are not related to User Account details, Billing inquiries, Order information, or Technical Support issues.
    """,
    output_type=InputGuardRailOutput,
)

Purpose: Determines if user input is within allowed scope (Account/Billing/Orders/Technical Support)
Output: Returns InputGuardRailOutput format
Rules: Allows brief greetings at conversation start, but blocks requests that are fundamentally off-topic

C. Guardrail Function Implementation

triage_agent.py Lines 20-35

@input_guardrail
async def off_topic_guardrail(
    wrapper: RunContextWrapper[UserAccountContext],
    agent: Agent[UserAccountContext],
    input: str,
):
    result = await Runner.run(
        input_guardrail_agent,
        input,
        context=wrapper.context,
    )

    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=result.final_output.is_off_topic,
    )

@input_guardrail: Decorator that registers the function as a guardrail
Parameters:
- wrapper: Execution context wrapper (access UserAccountContext via wrapper.context)
- agent: Current agent instance (for extensibility/logging)
- input: User input string to validate
Behavior:
- Runs input validation with input_guardrail_agent (passes context=wrapper.context on line 29)
- Returns GuardrailFunctionOutput
- tripwire_triggered: True if is_off_topic is True

D. Registering Guardrail with Main Agent

triage_agent.py Lines 96-102

triage_agent = Agent(
    name="Triage Agent",
    instructions=dynamic_triage_agent_instructions,
    input_guardrails=[
        off_topic_guardrail,
    ],
)

input_guardrails: List to register multiple guardrails
Execution order: User input → Guardrail validation → Main agent execution (if passed)

E. Guardrail Exception Handling

main.py Lines 51-67

        try:

            stream = Runner.run_streamed(
                triage_agent,
                message,
                session=session,
                context=user_account_ctx,
            )

            async for event in stream.stream_events():
                if event.type == "raw_response_event":

                    if event.data.type == "response.output_text.delta":
                        response += event.data.delta
                        text_placeholder.write(response.replace("$", "\$"))
        except InputGuardrailTripwireTriggered:
            st.write("I can't help you with that.")

InputGuardrailTripwireTriggered: Exception raised when guardrail is triggered
Handling: Displays "I can't help you with that." when blocked

5. Integrated Usage of Context and Guardrail

How Context is Passed to Guardrail

In main.py: Pass context=user_account_ctx
Inside Runner.run_streamed(): Wrap user_account_ctx with RunContextWrapper
Call off_topic_guardrail() function: Access via wrapper.context
Execute input_guardrail_agent: Pass context=wrapper.context (line 29) -> Guardrail agent can also access customer information

How Context is Used in Dynamic Prompt

Inside Runner.run_streamed(): Call dynamic_triage_agent_instructions(wrapper, agent)
Access wrapper.context.name, email, tier
Insert customer information into prompt:
- "The customer's name is nico."
- "The customer's tier is basic."
Call LLM with personalized prompt

6. Complete Execution Flow (Context + Guardrail)

[Step 1] Context Creation

Create user_account_ctx in main.py
UserAccountContext(customer_id=1, name="nico", tier="basic")[Step 2] User Input
↓
User: "What's the weather like today?"[Step 3] Call Runner.run_streamed()
↓
Runner.run_streamed(triage_agent, "What's the weather like today?", context=user_account_ctx) ← Pass Context[Step 4] Context Wrapping
↓
Wrap user_account_ctx with RunContextWrapper
Accessible via wrapper.context[Step 5] Input Guardrail Validation Starts
↓
Check triage_agent's input_guardrails list
→ Find off_topic_guardrail function[Step 6] Execute off_topic_guardrail()
↓
@input_guardrail decorator calls the function
wrapper: RunContextWrapper[UserAccountContext] (includes context)
agent: triage_agent instance
input: "What's the weather like today?"[Step 7] Execute Guardrail Agent (with Context)
↓
Runner.run(input_guardrail_agent, "What's the weather like today?", context=wrapper.context) ← Pass Context
→ input_guardrail_agent analyzes input with LLM
→ Determines "weather question is off-topic"
→ Returns InputGuardRailOutput(is_off_topic=True, reason="...")[Step 8] Create GuardrailFunctionOutput
↓
return GuardrailFunctionOutput(output_info=InputGuardRailOutput(...), tripwire_triggered=True)[Step 9] Exception Raised
↓
Since tripwire_triggered=True
→ InputGuardrailTripwireTriggered exception raised[Step 10] Exception Handling
↓
Caught in except block in main.py
→ Display "I can't help you with that."[Step 11] Main Agent Not Executed
↓
triage_agent is not executed (cost savings)

Example with Allowed Input (Context Usage)

[Steps 1-6] Same

↓

[Step 7] Execute Guardrail Agent

Input: "Check my account information"
→ Determines "account-related request"
→ Returns InputGuardRailOutput(is_off_topic=False, reason="")[Step 8] Guardrail Passed
↓
tripwire_triggered=False
→ No exception raised[Step 9] Execute Main Agent
↓
Call dynamic_triage_agent_instructions(wrapper, agent)
→ Access wrapper.context.name, email, tier
→ Generate prompt:
- "The customer's name is nico."
- "The customer's tier is basic."
→ Call LLM with personalized prompt
→ "Hello nico, I'll check your account information..."

7. Key Concepts Summary

Context Related

Concept	Description
UserAccountContext	Pydantic model containing customer account information
RunContextWrapper	Object that wraps context at execution time
wrapper.context	Access to actual UserAccountContext instance
context=user_account_ctx	Pass context to Runner

Input Guardrail Related

Concept	Description
@input_guardrail	Decorator that registers function as guardrail
input_guardrails	List that connects guardrails to agent
GuardrailFunctionOutput	Object that returns validation result and trigger status
InputGuardrailTripwireTriggered	Exception raised when blocked
tripwire_triggered	Whether guardrail was triggered

8. Interaction Between Context and Guardrail

Context Passing Path: main.py → Runner.run_streamed() → RunContextWrapper → wrapper.context
Using Context in Guardrail:
- Access customer information via wrapper.context
- Pass context=wrapper.context to guardrail agent
Using Context in Main Agent:
- Insert into prompt using wrapper.context in dynamic_triage_agent_instructions
Personalization:
- Personalize responses using customer name, tier, etc.

This structure validates user input before processing and uses context to generate personalized responses.

OPEN AI SDK - Customer support agent(1) -setup & full code

hyunsoo CHUNG — Tue, 30 Dec 2025 19:00:43 +0900

Now we make customer support ai agent. we want cooperating multiagent and input&output gaurdrail.

First, you should setup files like this.

1)main.py

import dotenv

dotenv.load_dotenv()

from openai import OpenAI

import asyncio

import streamlit as st

from agents import Runner, SQLiteSession, InputGuardrailTripwireTriggered, OutputGuardrailTripwireTriggered

from models import UserAccountContext

from my_agents.triage_agent import triage_agent

client = OpenAI()

user_account_ctx = UserAccountContext(

customer_id=1,

name="nico",

tier="basic",

)

if "session" not in st.session_state:

st.session_state["session"] = SQLiteSession(

"chat-history",

"customer-support-memory.db",

)

session = st.session_state["session"]

if "agent" not in st.session_state:

st.session_state["agent"] = triage_agent

async def paint_history():

messages = await session.get_items()

for message in messages:

if "role" in message:

with st.chat_message(message["role"]):

if message["role"] == "user":

st.write(message["content"])

else:

if message["type"] == "message":

st.write(message["content"][0]["text"].replace("$", "\\$"))

# Streamlit 실행 모델에 맞게 수정

try:

asyncio.run(paint_history())

except RuntimeError:

# 이미 실행 중인 이벤트 루프가 있는 경우 스킵

# (Streamlit이 재실행할 때 발생할 수 있음)

pass

except Exception as e:

# 다른 에러는 무시하고 계속 진행

st.error(f"Error loading history: {e}")

async def run_agent(message):

with st.chat_message("ai"):

text_placeholder = st.empty()

response = ""

st.session_state["text_placeholder"] = text_placeholder

try:

stream = Runner.run_streamed(

st.session_state["agent"],

message,

session=session,

context=user_account_ctx,

)

async for event in stream.stream_events():

if event.type == "raw_response_event":

if event.data.type == "response.output_text.delta":

response += event.data.delta

text_placeholder.write(response.replace("$", "\$"))

elif event.type == "agent_updated_stream_event":

if st.session_state["agent"].name != event.new_agent.name:

st.write(f" Transfered from {st.session_state["agent"].name} to {event.new_agent.name}")

st.session_state["agent"] = event.new_agent

text_placeholder = st.empty()

st.session_state["text_placeholder"] = text_placeholder

response = ""

except InputGuardrailTripwireTriggered:

st.write("I can't help you with that.")

except OutputGuardrailTripwireTriggered:

st.write("Cant show you that answer.")

st.session_state["text_placeholder"].empty()

message = st.chat_input(

"Write a message for your assistant",

)

if message:

with st.chat_message("human"):

st.write(message)

asyncio.run(run_agent(message))

with st.sidebar:

reset = st.button("Reset memory")

if reset:

asyncio.run(session.clear_session())

st.write(asyncio.run(session.get_items()))

2) models.py

from pydantic import BaseModel

from typing import Optional

class UserAccountContext(BaseModel):

customer_id: int

name: str

tier: str = "basic"

email: Optional[str] = None # premium entreprise

class InputGuardRailOutput(BaseModel):

is_off_topic: bool

reason: str

class HandoffData(BaseModel):

to_agent_name: str

issue_type: str

issue_description: str

reason: str

class TechnicalOutputGuardRailOutput(BaseModel):

contains_off_topic: bool

contains_billing_data: bool

contains_account_data: bool

reason: str

3)my_agents/triage_agent.py

import streamlit as st

from agents import (

Agent,

RunContextWrapper,

input_guardrail,

output_guardrail,

Runner,

GuardrailFunctionOutput,

handoff,

)

from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX

from agents.extensions import handoff_filters

from models import UserAccountContext, InputGuardRailOutput, HandoffData

from my_agents.account_agent import account_agent

from my_agents.order_agent import order_agent

from my_agents.billing_agent import billing_agent

from my_agents.technical_agent import technical_agent

input_guardrail_agent = Agent(

name="Input Guardrail Agent",

instructions="""

Ensure the user's request specifically pertains to User Account details, Billing inquiries, Order information, or Technical Support issues, and is not off-topic. If the request is off-topic, return a reason for the tripwire. You can make small conversation with the user, specially at the beginning of the conversation, but don't help with requests that are not related to User Account details, Billing inquiries, Order information, or Technical Support issues.

""",

output_type=InputGuardRailOutput,

)

@input_guardrail

async def off_topic_guardrail(

wrapper: RunContextWrapper[UserAccountContext],

agent: Agent[UserAccountContext],

input: str,

result = await Runner.run(

input_guardrail_agent,

input,

context=wrapper.context,

)

return GuardrailFunctionOutput(

output_info=result.final_output,

tripwire_triggered=result.final_output.is_off_topic,

)

def dynamic_triage_agent_instructions(

wrapper: RunContextWrapper[UserAccountContext],

agent: Agent[UserAccountContext],

return f"""

{RECOMMENDED_PROMPT_PREFIX}

You are a customer support agent. You ONLY help customers with their questions about their User Account, Billing, Orders, or Technical Support.

You call customers by their name.

The customer's name is {wrapper.context.name}.

The customer's email is {wrapper.context.email}.

The customer's tier is {wrapper.context.tier}.

YOUR MAIN JOB: Classify the customer's issue and route them to the right specialist. 절대로 technical_agent를 질문내용에 상관없이 라우팅하지 마세요. 반드시 기술관련 질문이어야 technical_agent로 라우팅하세요.

ISSUE CLASSIFICATION GUIDE:

TECHNICAL SUPPORT - Route here for:

- Product not working, errors, bugs

- App crashes, loading issues, performance problems

- Feature questions, how-to help

- Integration or setup problems

- "The app won't load", "Getting error message", "How do I..."

BILLING SUPPORT - Route here for:

- Payment issues, failed charges, refunds

- Subscription questions, plan changes, cancellations

- Invoice problems, billing disputes

- Credit card updates, payment method changes

- "I was charged twice", "Cancel my subscription", "Need a refund"

ORDER MANAGEMENT - Route here for:

- Order status, shipping, delivery questions

- Returns, exchanges, missing items

- Tracking numbers, delivery problems

- Product availability, reorders

- "Where's my order?", "Want to return this", "Wrong item shipped"

ACCOUNT MANAGEMENT - Route here for:

- Login problems, password resets, account access

- Profile updates, email changes, account settings

- Account security, two-factor authentication

- Account deletion, data export requests

- "Can't log in", "Forgot password", "Change my email"

CLASSIFICATION PROCESS:

1. Listen to the customer's issue

2. Ask clarifying questions if the category isn't clear

3. Classify into ONE of the four categories above

4. Explain why you're routing them: "I'll connect you with our [category] specialist who can help with [specific issue]"

5. Route to the appropriate specialist agent

SPECIAL HANDLING:

- Premium/Enterprise customers: Mention their priority status when routing

- Multiple issues: Handle the most urgent first, note others for follow-up

- Unclear issues: Ask 1-2 clarifying questions before routing

"""

def handle_handoff(

wrapper: RunContextWrapper[UserAccountContext],

input_data: HandoffData,

with st.sidebar:

st.write(

f"""

Handing off to {input_data.to_agent_name}

Reason: {input_data.reason}

Issue Type: {input_data.issue_type}

Description: {input_data.issue_description}

"""

)

def make_handoff(agent):

return handoff(

agent=agent,

on_handoff=handle_handoff,

input_type=HandoffData,

input_filter=handoff_filters.remove_all_tools,

)

triage_agent = Agent(

name="Triage Agent",

instructions=dynamic_triage_agent_instructions,

input_guardrails=[

off_topic_guardrail,

handoffs=[

make_handoff(technical_agent),

make_handoff(billing_agent),

make_handoff(account_agent),

make_handoff(order_agent),

)

4) tools.py

import streamlit as st

from agents import function_tool, AgentHooks, Agent, Tool, RunContextWrapper

from models import UserAccountContext

import random

from datetime import datetime, timedelta

# =============================================================================

# TECHNICAL SUPPORT TOOLS

# =============================================================================

@function_tool

def run_diagnostic_check(

context: UserAccountContext, product_name: str, issue_description: str

) -> str:

"""

Run a diagnostic check on the customer's product to identify potential issues.

Args:

product_name: Name of the product experiencing issues

issue_description: Description of the problem

"""

diagnostics = [

"✅ Server connectivity: Normal",

"✅ API endpoints: Responsive",

"⚠️ Cache memory: 85% full (recommend clearing)",

"✅ Database connections: Stable",

"⚠️ Last update: 7 days ago (update available)",

]

return f" Diagnostic results for {product_name}:\n" + "\n".join(diagnostics)

@function_tool

def provide_troubleshooting_steps(context: UserAccountContext, issue_type: str) -> str:

"""

Provide step-by-step troubleshooting instructions for common issues.

Args:

issue_type: Type of issue (connection, login, performance, crash, etc.)

"""

steps_map = {

"connection": [

"1. Check internet connectivity",

"2. Clear browser cache and cookies",

"3. Disable browser extensions temporarily",

"4. Try incognito/private browsing mode",

"5. Restart your router/modem",

"login": [

"1. Verify username and password",

"2. Check caps lock is off",

"3. Clear browser cache",

"4. Try password reset if needed",

"5. Disable VPN temporarily",

"performance": [

"1. Close unnecessary browser tabs",

"2. Clear browser cache",

"3. Check available RAM and storage",

"4. Update your browser",

"5. Restart the application",

"crash": [

"1. Update to latest version",

"2. Restart the application",

"3. Check system requirements",

"4. Disable conflicting software",

"5. Run in safe mode",

}

steps = steps_map.get(

issue_type.lower(),

[

"1. Restart the application",

"2. Check for updates",

"3. Contact support with error details",

)

context.add_troubleshooting_step(f"Provided {issue_type} troubleshooting steps")

return f" ️ Troubleshooting steps for {issue_type}:\n" + "\n".join(steps)

@function_tool

def escalate_to_engineering(

context: UserAccountContext, issue_summary: str, priority: str = "medium"

) -> str:

"""

Escalate a technical issue to the engineering team.

Args:

issue_summary: Brief summary of the technical issue

priority: Priority level (low, medium, high, critical)

"""

ticket_id = f"ENG-{random.randint(10000, 99999)}"

return f"""

Issue escalated to Engineering Team

Ticket ID: {ticket_id}

⚡ Priority: {priority.upper()}

Summary: {issue_summary}

Expected response: {2 if context.is_premium_customer() else 4} hours

""".strip()

# =============================================================================

# BILLING SUPPORT TOOLS

# =============================================================================

@function_tool

def lookup_billing_history(context: UserAccountContext, months_back: int = 6) -> str:

"""

Look up customer's billing history and payment records.

Args:

months_back: Number of months to look back (default 6)

"""

payments = []

for i in range(months_back):

date = datetime.now() - timedelta(days=30 * i)

amount = random.choice([29.99, 49.99, 99.99])

status = random.choice(["Paid", "Paid", "Paid", "Failed"])

payments.append(f"• {date.strftime('%b %Y')}: ${amount} - {status}")

return f" Billing History (Last {months_back} months):\n" + "\n".join(payments)

@function_tool

def process_refund_request(

context: UserAccountContext, refund_amount: float, reason: str

) -> str:

"""

Process a refund request for the customer.

Args:

refund_amount: Amount to refund

reason: Reason for the refund

"""

processing_days = 3 if context.is_premium_customer() else 5

refund_id = f"REF-{random.randint(100000, 999999)}"

return f"""

✅ Refund request processed

Refund ID: {refund_id}

Amount: ${refund_amount}

Reason: {reason}

⏱️ Processing time: {processing_days} business days

Refund will appear on original payment method

""".strip()

@function_tool

def update_payment_method(context: UserAccountContext, payment_type: str) -> str:

"""

Help customer update their payment method.

Args:

payment_type: Type of payment method (credit_card, paypal, bank_transfer)

"""

return f"""

Payment method update initiated

Type: {payment_type.replace('_', ' ').title()}

Secure link sent to: {context.email}

⏰ Link expires in: 24 hours

✅ No interruption to current service

""".strip()

@function_tool

def apply_billing_credit(

context: UserAccountContext, credit_amount: float, reason: str

) -> str:

"""

Apply account credit for billing issues or compensation.

Args:

credit_amount: Amount of credit to apply

reason: Reason for the credit

"""

return f"""

Account credit applied

Credit amount: ${credit_amount}

Reason: {reason}

⚡ Applied to account: {context.customer_id}

Confirmation sent to: {context.email}

""".strip()

# =============================================================================

# ORDER MANAGEMENT TOOLS

# =============================================================================

@function_tool

def lookup_order_status(context: UserAccountContext, order_number: str) -> str:

"""

Look up the current status and details of an order.

Args:

order_number: Customer's order number

"""

statuses = ["processing", "shipped", "in_transit", "delivered"]

current_status = random.choice(statuses)

tracking_number = f"1Z{random.randint(100000, 999999)}"

estimated_delivery = datetime.now() + timedelta(days=random.randint(1, 5))

return f"""

Order Status: {order_number}

️ Status: {current_status.title()}

Tracking: {tracking_number}

Estimated delivery: {estimated_delivery.strftime('%B %d, %Y')}

Shipping to: {context.email}

""".strip()

@function_tool

def initiate_return_process(

context: UserAccountContext, order_number: str, return_reason: str, items: str

) -> str:

"""

Start the return process for an order.

Args:

order_number: Order number to return

return_reason: Reason for return

items: Items being returned

"""

return_id = f"RET-{random.randint(100000, 999999)}"

return_label_fee = 0 if context.is_premium_customer() else 5.99

return f"""

Return initiated

Return ID: {return_id}

Order: {order_number}

Items: {items}

Return label fee: ${return_label_fee}

Return label sent to: {context.email}

⏰ Return window: 30 days

""".strip()

@function_tool

def schedule_redelivery(

context: UserAccountContext, tracking_number: str, preferred_date: str

) -> str:

"""

Schedule a redelivery for a failed delivery attempt.

Args:

tracking_number: Package tracking number

preferred_date: Customer's preferred delivery date

"""

return f"""

Redelivery scheduled

Tracking: {tracking_number}

New delivery date: {preferred_date}

Address confirmed: {context.email}

Driver will call 30 minutes before delivery

""".strip()

@function_tool

def expedite_shipping(context: UserAccountContext, order_number: str) -> str:

"""

Upgrade shipping speed for an order (premium customers only).

Args:

order_number: Order to expedite

"""

if not context.is_premium_customer():

return "❌ Expedited shipping upgrade requires Premium membership"

return f"""

⚡ Shipping expedited

Order: {order_number}

Upgraded to: Next-day delivery

No additional charge (Premium benefit)

Updated tracking sent to: {context.email}

""".strip()

# =============================================================================

# ACCOUNT MANAGEMENT TOOLS

# =============================================================================

@function_tool

def reset_user_password(context: UserAccountContext, email: str) -> str:

"""

Send password reset instructions to the customer's email.

Args:

email: Email address to send reset instructions

"""

reset_token = f"RST-{random.randint(100000, 999999)}"

return f"""

Password reset initiated

Reset link sent to: {email}

Reset token: {reset_token}

⏰ Link expires in: 1 hour

️ For security, link is single-use only

""".strip()

@function_tool

def enable_two_factor_auth(context: UserAccountContext, method: str = "app") -> str:

"""

Help customer set up two-factor authentication.

Args:

method: 2FA method (app, sms, email)

"""

setup_code = f"2FA-{random.randint(100000, 999999)}"

return f"""

Two-Factor Authentication Setup

Method: {method.upper()}

Setup code: {setup_code}

Instructions sent to: {context.email}

⚡ Enhanced security activated

""".strip()

@function_tool

def update_account_email(

context: UserAccountContext, old_email: str, new_email: str

) -> str:

"""

Process account email address change.

Args:

old_email: Current email address

new_email: New email address

"""

verification_code = f"VER-{random.randint(100000, 999999)}"

return f"""

Email update requested

From: {old_email}

To: {new_email}

Verification code: {verification_code}

⏰ Code expires in: 30 minutes

✅ Change will be activated after verification

""".strip()

@function_tool

def deactivate_account(

context: UserAccountContext, reason: str, feedback: str = ""

) -> str:

"""

Process account deactivation request.

Args:

reason: Reason for account deactivation

feedback: Optional feedback from customer

"""

return f"""

⚠️ Account deactivation initiated

Account: {context.customer_id}

Reason: {reason}

Feedback: {feedback if feedback else 'None provided'}

⏰ Account will be deactivated in 24 hours

Can be reactivated within 30 days

Confirmation sent to: {context.email}

""".strip()

@function_tool

def export_account_data(context: UserAccountContext, data_types: str) -> str:

"""

Generate export of customer's account data.

Args:

data_types: Types of data to export (profile, orders, billing, etc.)

"""

export_id = f"EXP-{random.randint(100000, 999999)}"

return f"""

Data export requested

Export ID: {export_id}

Data types: {data_types}

⏱️ Processing time: 2-4 hours

Download link will be sent to: {context.email}

Link expires in: 7 days

""".strip()

class AgentToolUsageLoggingHooks(AgentHooks):

async def on_tool_start(

self,

context: RunContextWrapper[UserAccountContext],

agent: Agent[UserAccountContext],

tool: Tool,

with st.sidebar:

st.write(f" **{agent.name}** starting tool: `{tool.name}`")

async def on_tool_end(

self,

context: RunContextWrapper[UserAccountContext],

agent: Agent[UserAccountContext],

tool: Tool,

result: str,

with st.sidebar:

st.write(f" **{agent.name}** used tool: `{tool.name}`")

st.code(result)

async def on_handoff(

self,

context: RunContextWrapper[UserAccountContext],

agent: Agent[UserAccountContext],

source: Agent[UserAccountContext],

with st.sidebar:

st.write(f" Handoff: **{source.name}** → **{agent.name}**")

async def on_start(

self,

context: RunContextWrapper[UserAccountContext],

agent: Agent[UserAccountContext],

with st.sidebar:

st.write(f" **{agent.name}** activated")

async def on_end(

self,

context: RunContextWrapper[UserAccountContext],

agent: Agent[UserAccountContext],

output,

with st.sidebar:

st.write(f" **{agent.name}** completed")

5) my_agents.technical_agent

from agents import (

Agent,

RunContextWrapper,

output_guardrail,

Runner,

GuardrailFunctionOutput,

)

from models import UserAccountContext

from tools import (

run_diagnostic_check,

provide_troubleshooting_steps,

escalate_to_engineering,

AgentToolUsageLoggingHooks,

)

from models import TechnicalOutputGuardRailOutput

technical_output_guardrail_agent = Agent(

name="Technical Support Guardrail",

instructions="""

Analyze the technical support response to check if it inappropriately contains:

- Billing information (payments, refunds, charges, subscriptions)

- Order information (shipping, tracking, delivery, returns)

- Account management info (passwords, email changes, account settings)

Technical agents should ONLY provide technical troubleshooting, diagnostics, and product support.

Return true for any field that contains inappropriate content for a technical support response.

""",

output_type=TechnicalOutputGuardRailOutput,

)

@output_guardrail

async def technical_output_guardrail(

wrapper: RunContextWrapper[UserAccountContext],

agent: Agent,

output: str,

result = await Runner.run(

technical_output_guardrail_agent,

output,

context=wrapper.context,

)

validation = result.final_output

triggered = (

validation.contains_off_topic

or validation.contains_billing_data

or validation.contains_account_data

)

return GuardrailFunctionOutput(

output_info=validation,

tripwire_triggered=triggered,

)

def dynamic_technical_agent_instructions(

wrapper: RunContextWrapper[UserAccountContext],

agent: Agent[UserAccountContext],

return f"""

You are a Technical Support specialist helping {wrapper.context.name}.

Customer tier: {wrapper.context.tier} {"(Premium Support)" if wrapper.context.tier != "basic" else ""}

YOUR ROLE: Solve technical issues with our products and services.

TECHNICAL SUPPORT PROCESS:

1. Gather specific details about the technical issue

2. Ask for error messages, steps to reproduce, system info

3. Provide step-by-step troubleshooting solutions

4. Test solutions with the customer

5. Escalate to engineering if needed (especially for premium customers)

INFORMATION TO COLLECT:

- What product/feature they're using

- Exact error message (if any)

- Operating system and browser

- Steps they took before the issue occurred

- What they've already tried

TROUBLESHOOTING APPROACH:

- Start with simple solutions first

- Be patient and explain technical steps clearly

- Confirm each step works before moving to the next

- Document solutions for future reference

{"PREMIUM PRIORITY: Offer direct escalation to senior engineers if standard solutions don't work." if wrapper.context.tier != "basic" else ""}

"""

technical_agent = Agent(

name="Technical Support Agent",

instructions=dynamic_technical_agent_instructions,

tools=[

run_diagnostic_check,

provide_troubleshooting_steps,

escalate_to_engineering,

hooks=AgentToolUsageLoggingHooks(),

output_guardrails=[

technical_output_guardrail,

)

hyunsoo's blog

Google ADK: Youtube shorts maker(1)- full code and agent pipleline

YouTube Shorts Maker - Complete Code Collection

youtube_shorts_maker/__init__.py

youtube_shorts_maker/agent.py

youtube_shorts_maker/prompt.py

youtube_shorts_maker/sub_agents/content_planner/agent.py

youtube_shorts_maker/sub_agents/content_planner/prompt.py

youtube_shorts_maker/sub_agents/asset_generator/agent.py

youtube_shorts_maker/sub_agents/asset_generator/prompt.py

youtube_shorts_maker/sub_agents/asset_generator/image_generator/agent.py

youtube_shorts_maker/sub_agents/asset_generator/image_generator/prompt_builder/agent.py

youtube_shorts_maker/sub_agents/asset_generator/image_generator/prompt_builder/prompt.py

youtube_shorts_maker/sub_agents/asset_generator/image_generator/image_builder/agent.py

youtube_shorts_maker/sub_agents/asset_generator/image_generator/image_builder/prompt.py

youtube_shorts_maker/sub_agents/asset_generator/image_generator/image_builder/tools.py

youtube_shorts_maker/sub_agents/asset_generator/voice_generator/agent.py

youtube_shorts_maker/sub_agents/asset_generator/voice_generator/prompt.py

youtube_shorts_maker/sub_agents/asset_generator/voice_generator/tools.py

youtube_shorts_maker/sub_agents/video_assembler/agent.py

youtube_shorts_maker/sub_agents/video_assembler/prompt.py

youtube_shorts_maker/sub_agents/video_assembler/tools.py

Summary

Google ADK: Financial Advisor(4)- state, artifact, toolcontext

Step 6: Save Report (Optional)

6-1. Main Agent LLM Call #12 (Report Generation)

6-2. Report Saving Function Execution

Total LLM Call Summary

ToolContext Detailed Description

Role of ToolContext

How ToolContext is Passed

Major Properties and Methods of ToolContext

1. tool_context.state

2. tool_context.save_artifact(filename, artifact)

ToolContext Passing Conditions

Lifecycle of ToolContext

State Management System Detailed Description

What is State?

Creation and Access of State

1. Access via ToolContext.state

2. Structure of State

Auto-save via output_key

Actual Code Example

Step-by-Step State Changes

Characteristics of State

Artifact System Detailed Description

What is an Artifact?

Artifact Creation Process

1. Creating an Artifact Object

2. Detailed Steps for Saving an Artifact (Code Analysis)

Artifact Storage Location

Difference between Artifact and State

Relationship between State and Artifact

Tool Function Parameter Determination Method

Core Concept: The LLM automatically determines parameters.

Operating Principle

Actual Example

Important Points

Data Flow Diagram

Google ADK: Financial Advisor(3)- json communication between llm and adk

System Overview

Real-world Example: AAPL Stock Analysis Request

Explaining the case where a user asks, "Give me investment advice for AAPL stock."

Detailed Step-by-Step Process

Step 1: Receiving User Request and Initial LLM Call

User Input

Main Agent LLM Call #1

Step 2: Executing Data Analyst Sub-agent

2-1. Data Analyst Agent Initialization and LLM Call #2

2-2. Actual Tool Function Execution (No LLM Call, Direct Execution)

2-3. Data Analyst LLM Call #3 (Result Analysis)

Step 5: Main Agent's Final Analysis and Advice

5-1. Main Agent LLM Call #10 (Comprehensive Analysis)

5-2. User Response (Example)

5-3. Main Agent LLM Call #11 (Final Advice Generation)

Google ADK: Financial Advisor(2)- full code

Google ADK: Financial Advisor(1)- setup

OPEN AI SDK - Customer support agent(5) - Output_gaurdrail

1. Purpose and Concept of Output Guardrail

2. Data Model Definition

`youtube_shorts_maker/init.py`

`youtube_shorts_maker/agent.py`

`youtube_shorts_maker/prompt.py`

`youtube_shorts_maker/sub_agents/content_planner/agent.py`

`youtube_shorts_maker/sub_agents/content_planner/prompt.py`

`youtube_shorts_maker/sub_agents/asset_generator/agent.py`

`youtube_shorts_maker/sub_agents/asset_generator/prompt.py`

`youtube_shorts_maker/sub_agents/asset_generator/image_generator/agent.py`

`youtube_shorts_maker/sub_agents/asset_generator/image_generator/prompt_builder/agent.py`

`youtube_shorts_maker/sub_agents/asset_generator/image_generator/prompt_builder/prompt.py`

`youtube_shorts_maker/sub_agents/asset_generator/image_generator/image_builder/agent.py`

`youtube_shorts_maker/sub_agents/asset_generator/image_generator/image_builder/prompt.py`

`youtube_shorts_maker/sub_agents/asset_generator/image_generator/image_builder/tools.py`

`youtube_shorts_maker/sub_agents/asset_generator/voice_generator/agent.py`

`youtube_shorts_maker/sub_agents/asset_generator/voice_generator/prompt.py`

`youtube_shorts_maker/sub_agents/asset_generator/voice_generator/tools.py`

`youtube_shorts_maker/sub_agents/video_assembler/agent.py`

`youtube_shorts_maker/sub_agents/video_assembler/prompt.py`

`youtube_shorts_maker/sub_agents/video_assembler/tools.py`