Agent Configuration: Environment, Metadata, and Overrides

In the early stages of development, it is tempting to hard-code your agent's system prompt and model settings directly into your Python files. However, as your system grows from one agent to ten, and from local testing to production deployment, hard-coded configurations become a nightmare for maintenance, security, and versioning.

The Gemini ADK encourages a "Configuration-First" approach. By separating the Agent Logic (the code) from the Agent Metadata (the settings), you can iterate on your agent's persona and model parameters without ever touching a line of executable code. In this lesson, we will explore the best practices for managing environment variables, external configuration files, and dynamic runtime overrides.

1. The Three Layers of Configuration

A professional agentic system typically manages configuration in three distinct layers.

Layer 1: Environmental Variables (Secrets & Infrastructure)

This layer contains data that changes based on where the code is running (Local vs. AWS vs. Google Cloud).

API Keys: GEMINI_API_KEY
Project IDs: GCP_PROJECT_ID
Endpoint URLs: DATABASE_URL

Layer 2: Static Configuration Files (Personas & Tunables)

This layer defines the "What" and "Who" of the agent. It is usually stored in version control (Git).

System Prompts: The character and mission of the agent.
Model Parameters: temperature, top_p, max_output_tokens.
Tool Access: A list of tools the agent is allowed to use.

Layer 3: Dynamic Overrides (Per-Request Logic)

This layer allows you to tweak the agent's behavior based on the specific User or Context.

User Tone: Adjusting the agent to be "Expert" for one user and "Beginner" for another.
Priority: Increasing the max_iterations for a high-priority business task.

2. Personas as Code: The YAML Configuration Pattern

One of the most effective strategies for managing agents in Gemini ADK is using YAML files for personas. This allows non-technical stakeholders (like Product Managers or Content Strategists) to edit the agent's "personality" without needing to understand Python.

Example: `researcher_agent.yaml`

agent_metadata:
  name: "DeepSearch Researcher"
  version: "1.2.0"
  model: "gemini-1.5-pro"

generation_config:
  temperature: 0.1
  top_p: 0.95
  max_output_tokens: 2048

system_instructions: |
  You are a top-tier research assistant. Your goal is to provide 
  fact-checked, objective summaries of complex topics. 
  ALWAYS cite your sources using [1], [2] format.
  If you are unsure about a fact, state it explicitly.

capabilities:
  - web_search
  - internal_knowledge_base
  - python_interpreter

Why YAML?

Readability: It's much cleaner than multi-line strings in Python.
Git Friendly: You can easily see exactly how a prompt changed in a Pull Request.
Validation: You can use a library like Pydantic to ensure the YAML file contains all required fields before starting the agent.

3. Managing Secrets and Security

Never, under any circumstances, store your GEMINI_API_KEY in your configuration files.

The Recommended Flow:

Local Dev: Use a .env file (and add it to .gitignore).
Production: Use a specialized Secret Manager (e.g., Google Cloud Secret Manager or AWS Secrets Manager).
In Code: Fetch the secret at the very last moment during the Initialization Phase of the lifecycle.

import os
from dotenv import load_dotenv

# Load .env only in local development
load_dotenv()

# Professional way to fetch a key
api_key = os.getenv("GEMINI_API_KEY")
if not api_key:
    raise ValueError("GEMINI_API_KEY is not set. The agent cannot start.")

4. Dynamic Overrides: The "Context-Aware" Agent

Sometimes, you need to change the agent's behavior for a specific user. For example, a "Premium" user might get access to Gemini Pro, while a "Free" user is restricted to Gemini Flash.

Implementation: The Override Wrapper

def create_agent(user_tier: str):
    # Base Config (Loaded from YAML)
    config = load_yaml("agent_config.yaml")
    
    # Layer 3: Dynamic Overrides
    if user_tier == "premium":
        config['model'] = "gemini-1.5-pro"
        config['max_iterations'] = 10
    else:
        config['model'] = "gemini-1.5-flash"
        config['max_iterations'] = 3
        
    return genai.GenerativeModel(
        model_name=config['model'],
        # ... other settings
    )

5. Architectural Diagram: The Config Pipeline

Understanding the flow of configuration data helps in debugging "Identity Crisis" issues in agents.

graph LR
    subgraph "Storage"
    A[.env / Secrets Manager]
    B[YAML Persona Files]
    C[Runtime Database]
    end
    
    subgraph "Validation Layer (Pydantic)"
    D[Config Loader]
    end
    
    subgraph "The Agent"
    E[Gemini ADK Agent Instance]
    end
    
    A --> D
    B --> D
    C --> D
    D -->|Validated Object| E
    
    style E fill:#4285F4,color:#fff

6. Versioning Prompts: The "PromptOps" Approach

Prompts are essentially non-deterministic code. Just as you version your Python code, you must version your prompts.

The Problem with "Snapshotting"

If you update your System Prompt in the YAML file and it breaks your agent's ability to use a specific tool, you need to be able to "Roll Back" instantly.

Best Practices:

Commit History: Every change to a persona YAML should have a descriptive commit message: "Updated researcher prompt to include sourcing requirements."
A/B Testing: Run two instances of the agent—one with the "v1.0" prompt and one with "v1.1"—and compare their performance using an evaluation framework (which we will cover in Module 12).

7. Configuration Anti-Patterns

Anti-Pattern: The Mega-Prompt. Putting 2,000 lines of "instructions" into one config. The model will lose the middle. Solution: Use smaller prompts and rely on Few-Shot Examples.
Anti-Pattern: Config Leakage. Accurately passing a development API key into your production config. Solution: Use strict environment segregation (separate .yaml files for dev, stage, and prod).
Anti-Pattern: Tool Discovery via Text. Telling the model "You can use a tool called X" in the prompt text, but not actually binding the tool in the code. Solution: Always use the ADK's tools=[] parameter.

8. Summary and Exercises

Configuration is the Control Panel of your agentic system.

Environment Variables handle infrastructure.
YAML Personas handle behavior and logic.
Dynamic Overrides handle personalization.
Validation ensures stability.

Exercises

Config Refactoring: Take an existing "hard-coded" agent script you've written in previous lessons. Refactor it so that the System Prompt is loaded from a separate config.json or config.yaml file.
Safety Override: Design a config schema that includes a max_spend field. Write a snippet of Python that checks if an agent's planned action exceeds this spend before allowing it to proceed.
Multi-Persona Design: Create two YAML files: creative_writer.yaml and factual_editor.yaml. Write a "Supervisor" script that switches between these two configs based on whether the user asks for "Drafting" or "Proofreading."

In the next module, we leave the "Structure" behind and dive into the "Message," exploring Prompting and Agent Instructions in the Gemini era.