Forem: Hiroshi Toyama

Managing AI Agent Skills with `npx skills`: A Practical Guide

Hiroshi Toyama — Sat, 11 Apr 2026 08:04:45 +0000

The Problem

AI agents like Claude Code, Cursor, and GitHub Copilot don't inherently know how to use every tool in your stack. You need a way to teach them. That's what npx skills does — it's a package manager for AI agent behaviors, built by Vercel Labs.

npx skills add microsoft/playwright-cli

This command fetches a SKILL.md from the specified GitHub repository and installs it into your agent's config directory (.agents/skills/ or .claude/skills/ depending on the agent).

How It Works

GitHub as the Registry

Unlike npm which uses npmjs.com, skills uses GitHub as its registry. The microsoft/playwright-cli argument maps directly to https://github.com/microsoft/playwright-cli. Any public GitHub repo with a SKILL.md at root is a valid skill source.

You can also install by full URL:

npx skills add https://github.com/microsoft/playwright-cli

SKILL.md as the Package Entry Point

Each skill repo contains a SKILL.md — the equivalent of index.js in an npm package. It contains:

Metadata: name and description of the skill
Tool definitions: commands the AI can invoke (e.g. playwright test)
Prompt instructions: when and how the AI should use the tool

.skills.json + skills-lock.json = package.json + package-lock.json

Concept	npm	skills CLI
Dependency manifest	`package.json`	`.skills.json`
Lock file	`package-lock.json`	`skills-lock.json`
Install directory	`node_modules/`	`.agents/skills/`
Registry	npmjs.com	GitHub
Install command	`npm install`	`npx skills experimental_install`

After npx skills add, your .skills.json will look like:

{
  "skills": [
    {
      "name": "playwright-cli",
      "remote": "microsoft/playwright-cli",
      "version": "latest"
    }
  ]
}

Key Commands

# Add a skill
npx skills add vercel-labs/agent-skills

# Add globally (user-level, not project-level)
npx skills add vercel-labs/agent-skills -g

# Target specific agents
npx skills add vercel-labs/agent-skills --agent claude-code cursor

# List installed skills
npx skills list
npx skills ls -g           # global skills
npx skills ls -a cursor    # filter by agent

# Search the registry
npx skills find typescript

# Update all skills
npx skills update

# Restore from lock file (equivalent of npm ci)
npx skills experimental_install

# Sync from node_modules to agent directories
npx skills experimental_sync

# Scaffold a new skill
npx skills init my-skill

Gotchas

`remove` Doesn't Update the Lock File

This is the biggest footgun:

npx skills rm microsoft/playwright-cli --all

This removes the skill files from your agent directories, but leaves the entry in skills-lock.json. The next time someone runs experimental_install, the skill comes back.

Workaround:

Run npx skills remove as usual
Manually edit .skills.json to remove the entry
Delete skills-lock.json
Run npx skills update or add remaining skills to regenerate a clean lock file

`experimental_` Prefix is Real

experimental_install and experimental_sync are genuinely experimental. The sync command in the current version is not npx skills sync — it's npx skills experimental_install to restore from lock file, and npx skills experimental_sync to sync from node_modules.

Cache Behavior with npx

npx skills may run a cached older version. Force latest:

npx skills@latest add <repo>

For projects where everyone needs the same CLI version, add it as a devDependency:

npm install --save-dev skills

CI/CD Integration

Add to your CI setup to restore skills on each run:

- name: Restore AI agent skills
  run: npx skills experimental_install

This ensures every developer and CI environment uses exactly the same skill versions as defined in skills-lock.json.

Creating Your Own Skill

Any GitHub repo with a SKILL.md is installable. Create one with:

npx skills init my-skill

This scaffolds a SKILL.md that you push to GitHub. Anyone can then install it with:

npx skills add yourusername/my-skill

Browse existing skills at skills.sh.

Summary

npx skills is npm for AI agent capabilities. The mental model maps cleanly:

SKILL.md = index.js
.skills.json = package.json
skills-lock.json = package-lock.json
experimental_install = npm ci
GitHub = npm registry

The tooling is still experimental — particularly the lock file management on remove — but it's already useful for ensuring consistent AI behavior across team environments.

Deploying a Google ADK Agent to Vertex AI Agent Engine with Terraform

Hiroshi Toyama — Mon, 30 Mar 2026 12:45:33 +0000

Most documentation for Vertex AI Agent Engine focuses on the Python SDK (vertexai.agent_engines.create). That works fine for one-off deployments, but if you want your agent infrastructure managed declaratively alongside the rest of your GCP resources, Terraform is the right tool.

This post walks through a complete Terraform setup for deploying a Google ADK agent to Vertex AI Agent Engine using google_vertex_ai_reasoning_engine.

Prerequisites

Terraform >= 1.5
google or google-beta provider
aiplatform.googleapis.com enabled
A Google ADK agent wrapped in AdkApp

How Agent Engine Deployment Works

The deployment model is straightforward: tar.gz your source code, base64-encode it, and pass it to the API via inline_source. The runtime handles dependency installation, session management, and streaming — you just provide the entrypoint.

The Agent Entrypoint

The key requirement is an AdkApp instance at the module level. This is what Terraform's entrypoint_object points to.

# src/myagent/agent.py
from google.adk.agents import Agent
from vertexai.agent_engines import AdkApp

def get_weather(city: str) -> dict:
    """Returns weather for a given city."""
    return {"city": city, "weather": "sunny"}

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",
    description="Answers weather questions",
    instruction="Answer the user's weather question using the get_weather tool.",
    tools=[get_weather],
)

# This is what entrypoint_object references
agent_engine = AdkApp(agent=root_agent)

Wrapping in AdkApp automatically exposes create_session, stream_query, and other ADK methods as callable endpoints.

Building the Source Archive

Agent Engine expects a base64-encoded tar.gz containing your source files and a requirements.txt. Here's a minimal build script that uses only the Python standard library:

# scripts/build_source.py
import base64
import io
import json
import sys
import tarfile
from pathlib import Path


def main():
    query = json.load(sys.stdin)
    project_root = Path(query["project_root"]).resolve()
    src_dir = project_root / "src"
    requirements = project_root / "requirements.txt"

    buf = io.BytesIO()
    with tarfile.open(fileobj=buf, mode="w:gz") as tar:
        for path in sorted(src_dir.rglob("*.py")):
            arcname = path.relative_to(project_root)
            tar.add(path, arcname=str(arcname))
        tar.add(requirements, arcname="requirements.txt")

    b64 = base64.b64encode(buf.getvalue()).decode()
    json.dump({"base64": b64}, sys.stdout)


if __name__ == "__main__":
    main()

The requirements.txt lists PyPI package names — the Agent Engine runtime installs them at deploy time:

google-adk>=1.0.0
google-cloud-aiplatform[agent_engines]>=1.93.0

Terraform Configuration

`provider.tf`

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 6.0"
    }
    google-beta = {
      source  = "hashicorp/google-beta"
      version = "~> 6.0"
    }
  }
}

provider "google-beta" {
  project = var.project_id
  region  = "asia-northeast1"
}

Wiring the Archive Build

Use the external data source to invoke the build script during terraform plan/apply:

data "external" "agent_source" {
  program = ["python3", "${path.module}/scripts/build_source.py"]

  query = {
    project_root = "${path.module}/../.."
  }
}

Every apply picks up the latest source automatically.

The Agent Engine Resource

resource "google_vertex_ai_reasoning_engine" "my_agent" {
  provider     = google-beta
  display_name = "my-agent-${var.env}"
  description  = "ADK weather agent"
  region       = "asia-northeast1"

  spec {
    agent_framework = "google-adk"
    service_account = var.service_account_email

    class_methods = jsonencode([
      { name = "create_session", api_mode = "" },
      { name = "get_session",    api_mode = "" },
      { name = "list_sessions",  api_mode = "" },
      { name = "delete_session", api_mode = "" },
      { name = "stream_query",   api_mode = "stream" },
    ])

    source_code_spec {
      inline_source {
        source_archive = data.external.agent_source.result.base64
      }

      python_spec {
        entrypoint_module = "src.myagent.agent"
        entrypoint_object = "agent_engine"
        requirements_file = "requirements.txt"
        version           = "3.12"
      }
    }

    deployment_spec {
      env {
        name  = "LOG_LEVEL"
        value = "INFO"
      }

      secret_env {
        name = "API_TOKEN"
        secret_ref {
          secret  = "my-api-token"
          version = "latest"
        }
      }
    }
  }
}

Block Reference

Block	Purpose
`agent_framework`	Must be `"google-adk"` — tells the runtime which framework to use
`class_methods`	Enumerates callable methods; `api_mode = "stream"` enables SSE
`inline_source`	Embeds the base64 tar.gz directly — no GCS bucket needed
`python_spec`	Specifies the entrypoint and Python version
`deployment_spec`	Injects env vars and Secret Manager secrets at runtime

`class_methods` in Detail

Every ADK method you want to expose must be declared explicitly:

class_methods = jsonencode([
  { name = "create_session", api_mode = "" },
  { name = "get_session",    api_mode = "" },
  { name = "list_sessions",  api_mode = "" },
  { name = "delete_session", api_mode = "" },
  { name = "stream_query",   api_mode = "stream" },
])

api_mode = "stream" makes the method return a Server-Sent Events stream. Only stream_query needs this — the rest are standard request/response.

Gotchas

Provider choice matters. google_vertex_ai_reasoning_engine is available in both google and google-beta providers. Make sure the provider attribute matches whichever you configure.

The external data source re-runs on every plan. This is by design — you always get the latest source. If your build script is slow, consider caching or only calling it on apply.

entrypoint_module uses dot notation, not file paths. src.myagent.agent maps to src/myagent/agent.py in the archive. Match this to your actual directory structure.

Secret Manager secrets must already exist. Terraform reads existing secrets via data sources — it doesn't create them. Provision secrets separately before running apply.

Deploy and Verify

terraform init
terraform plan
terraform apply

Export the resource name to call the agent from Python:

output "agent_engine_resource_name" {
  value = google_vertex_ai_reasoning_engine.my_agent.name
}

import vertexai
from vertexai.agent_engines import AdkApp

vertexai.init(project="my-project", location="asia-northeast1")

agent = AdkApp.from_resource_name(
    "projects/my-project/locations/asia-northeast1/reasoningEngines/<ID>"
)

session = agent.create_session(user_id="user-1")
for chunk in agent.stream_query(
    user_id="user-1",
    session_id=session["id"],
    message="What's the weather in Tokyo?",
):
    print(chunk)

Summary

google_vertex_ai_reasoning_engine is available in both google and google-beta providers
Source code is delivered as a base64 tar.gz via inline_source — no GCS required
A minimal Python script using only stdlib is enough to produce the archive
class_methods must explicitly enumerate every ADK method you want to expose
Secret Manager integration is declarative via secret_env blocks

Terraforming Agent Engine makes cleanup (terraform destroy), environment promotion, and drift detection straightforward. The ADK + Terraform combination has sparse documentation, so hopefully this fills the gap.

AI-Driven Chrome Extension Development with WXT and Chrome DevTools MCP

Hiroshi Toyama — Sun, 29 Mar 2026 12:21:39 +0000

The Problem

Building a Chrome extension that modifies a third-party web app is a unique challenge. The DOM structure is opaque, class names are minified and change between deployments, and there's no official API to hook into. Traditional extension development looks like this:

Inspect the DOM manually in DevTools
Write selectors and content scripts
Reload the extension
Check if it works
Repeat

This cycle is slow. I wanted an AI coding agent that could see the actual browser state and verify its own changes — not just generate code blindly.

That's how I arrived at this stack: WXT for the extension framework, Chrome DevTools MCP for giving the AI agent browser access, and Cursor as the IDE tying it all together.

The Stack

Tool	Role
WXT	Chrome extension framework (TypeScript, hot reload, Manifest V3)
Chrome DevTools MCP	MCP server that exposes Chrome DevTools Protocol to AI agents
Cursor	AI-powered IDE with native MCP support

Step 1: WXT with a Fixed CDP Port

WXT is a framework that wraps Chrome extension development with file-based routing, hot reload, and TypeScript support out of the box. The key insight is that WXT's runner can launch Chrome with custom Chromium args — including --remote-debugging-port.

// wxt.config.ts
import { defineConfig } from 'wxt';

export default defineConfig({
  manifest: {
    name: 'My Extension',
    version: '1.0',
    permissions: ['storage'],
  },
  extensionApi: 'chrome',
  runner: {
    chromiumArgs: [
      '--remote-debugging-port=9222',
      `--user-data-dir=${process.cwd()}/.chrome-debug-profile`,
      '--exclude-switches=enable-automation',
    ],
    startUrls: ['https://example.com'],
  },
});

Three things to note:

--remote-debugging-port=9222 — Exposes the Chrome DevTools Protocol on a fixed port. The MCP server connects here.
--user-data-dir — A dedicated profile directory, separate from your daily Chrome. Login sessions persist across dev restarts. Add this to .gitignore — it contains cookies and session tokens that must not be pushed to a repository.
--exclude-switches=enable-automation — Without this, some sites detect the "automated" browser and block sign-in.

When you run wxt (or npm run dev), WXT launches Chrome with these args, loads your extension, and watches for file changes — all in one command.

Step 2: Chrome DevTools MCP Configuration

MCP (Model Context Protocol) lets AI agents call external tools. Chrome DevTools MCP is an MCP server that wraps the Chrome DevTools Protocol — giving your AI agent the ability to navigate pages, evaluate JavaScript, take screenshots, and inspect the DOM.

Configuration lives in .cursor/mcp.json:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--browserUrl=http://127.0.0.1:9222"
      ]
    }
  }
}

That's it. When Cursor starts, it spins up the MCP server, which connects to Chrome on port 9222. The AI agent can now see and interact with your browser.

Step 3: The Dev Script (Optional but Recommended)

A small shell script wrapping the two main workflows keeps things ergonomic:

./dev.sh dev      # WXT dev server + Chrome (hot reload + MCP)
./dev.sh start    # Load built extension (no hot reload, MCP only)
./dev.sh stop     # Kill debug Chrome
./dev.sh status   # Check CDP connection

dev is the primary mode — WXT handles everything and you get hot reload. start is for testing production builds with MCP inspection. The script handles edge cases like port conflicts, PID management, and connection verification via curl http://localhost:9222/json/version.

The Workflow in Practice

1. Start the environment

npm run dev   # or ./dev.sh dev

Chrome opens automatically with the extension loaded. WXT watches for file changes. The MCP server connects to port 9222. Cursor's AI agent can now see the browser.

2. AI inspects current state

The AI agent evaluates JavaScript in the browser context to understand the current DOM:

// The agent runs this via MCP
evaluate_script({
  function: `() => ({
    injectedStyle: !!document.getElementById('my-extension-styles'),
    buttonCount: document.querySelectorAll('.my-custom-button').length,
    panelVisible: !!document.getElementById('my-panel'),
  })`
})

The agent can verify its own changes without you switching context. It writes code, WXT hot-reloads, and the agent checks if the DOM updated correctly.

3. AI verifies changes through the browser

Here's the key difference from normal AI-assisted coding. Instead of:

"I've added the panel. Please refresh and check if it works."

The AI does this:

"I've added the panel. Let me verify... [evaluates script via MCP] ... The #my-panel element exists, has 5 child entries, and is positioned correctly. Rendering looks good."

Text-based DOM verification is preferred over screenshots — it's faster, cheaper, and more precise:

// Good: structured verification
evaluate_script(() => {
  const buttons = document.querySelectorAll('.my-button');
  return {
    count: buttons.length,
    firstButton: buttons[0]?.outerHTML.substring(0, 200),
  };
});

// Screenshots only when you need visual layout confirmation
take_screenshot()

Tips and Gotchas

Content Script Isolation

Chrome extension content scripts run in an isolated world. Variables set on window in the content script are invisible to evaluate_script via MCP, because MCP evaluates in the page context.

The workaround: verify through DOM side effects, not global variables.

// Won't work: window globals are in the isolated world
evaluate_script(() => window.myExtensionState) // → undefined

// Works: check the DOM changes the extension made
evaluate_script(() => ({
  styleInjected: !!document.getElementById('my-extension-styles'),
  panelExists: !!document.getElementById('my-panel'),
}))

Selector Strategy for Third-Party UIs

When building extensions for sites you don't control, selectors break frequently. A fallback chain helps:

const el =
  document.querySelector('[aria-label*="Submit"]') ||
  document.querySelector('[data-test-id="submit"]') ||
  document.querySelector('.submit-btn');

Priority:

ARIA attributes (aria-label, role) — most stable across updates
Semantic attributes (data-test-id) — moderately stable
Class names — last resort, always provide as fallback

You can even build a DOM analyzer shortcut (Ctrl+Shift+D) that exports the page structure in a format the AI agent can consume. When selectors break, press the shortcut, paste the output into Cursor, and the agent updates the fallback selectors.

Async DOM Waiting

SPA elements appear asynchronously. Rather than fragile setTimeout chains, use polling with bounded retries:

let retries = 0;
const interval = setInterval(() => {
  const el = document.querySelector(selector);
  if (el || retries++ > 10) {
    clearInterval(interval);
    if (el) callback(el);
  }
}, 500);

If the element never appears, fail silently — no console spam.

Google Login Gotcha

When Chrome launches with --remote-debugging-port, Google sometimes detects it as an "unsafe browser" and blocks sign-in. The --exclude-switches=enable-automation flag helps, but if it's not enough:

Launch Chrome with the dedicated profile (without WXT)
Sign in manually
Close Chrome
Now run npm run dev — WXT reuses the same profile with the valid session

The dedicated --user-data-dir persists your login across dev sessions.

`--user-data-dir` and Security

The dedicated profile serves two purposes:

Isolation from your daily Chrome: The dev browser doesn't touch your bookmarks, extensions, or sessions — and your personal credentials don't leak into the dev environment.
Minimal credentials: Only log into what you need for development. Don't sign into personal Gmail or other unrelated accounts.

Keep in mind:

Always add the profile directory to .gitignore. It contains cookies, session tokens, and LocalStorage.

.chrome-debug-profile/

CDP port 9222 is accessible from localhost. --remote-debugging-port binds to 127.0.0.1 by default, but any process on your machine can access all open tabs. Only run it during active development.
Don't use this on shared machines. While CDP is open, anyone on the same machine can control the browser session.

Getting Started

If you want to try this workflow:

1. Create a WXT project

npm create wxt@latest my-extension
cd my-extension

2. Add CDP port to `wxt.config.ts`

runner: {
  chromiumArgs: [
    '--remote-debugging-port=9222',
    `--user-data-dir=${process.cwd()}/.chrome-debug-profile`,
    '--exclude-switches=enable-automation',
  ],
},

3. Create `.cursor/mcp.json`

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--browserUrl=http://127.0.0.1:9222"]
    }
  }
}

4. Run

npm run dev

Chrome launches with CDP enabled, Cursor's agent connects. Your AI agent can now see your browser.

Why This Workflow Matters

The traditional Chrome extension development loop is write → reload → manually check → repeat. With WXT + Chrome DevTools MCP, it becomes write → auto-reload → AI verifies → iterate — and the AI agent can do the first and last steps too.

Debugging goes from "read console logs, set breakpoints, manually reproduce" to "AI evaluates scripts in the live browser and reports what's happening."
Selector maintenance goes from "open DevTools, inspect element, copy selector, paste into code" to "AI reads the DOM and updates fallback selectors."
Feature development goes from "code blind, test manually" to "AI writes code, checks DOM state, fixes issues — all in one turn."

This doesn't replace understanding your own extension. But it dramatically shortens the feedback loop, especially for the tedious parts of third-party DOM manipulation.

BigQuery Global Queries: Join Data Across Regions Without ETL

Hiroshi Toyama — Sun, 22 Mar 2026 12:38:06 +0000

As of February 2026, Google released BigQuery Global Queries in Preview. It lets you join tables from completely different geographic regions — say, asia-northeast1 (Tokyo) and us-central1 (Iowa) — in a single SQL statement. No ETL, no data movement pipelines, no manual copying.

This post covers how it actually works under the hood, what it costs, and the gotchas you need to know before using it in production.

The Old Problem

BigQuery historically required all datasets referenced in a single query to live in the same location. If your sales data was in Tokyo and your user master was in the US, you had two options:

Copy one dataset to the other region (ETL pipeline, operational overhead).
Run two separate queries and join the results in application code.

Global Queries eliminates this constraint.

How It Works: 4-Stage Execution

When you run a global query, BigQuery orchestrates the execution across regions transparently:

1. Distributed Execution

The Query Optimizer analyzes the query, identifies which tables live in which regions, and assigns the querying region as the Primary Region (the "leader"). Workers in each remote region receive their execution assignments in parallel.

2. Data Pushdown

This is the most critical stage — and the one that makes global queries economically viable.

Before any data crosses the network, BigQuery applies three types of pushdown to minimize transfer size:

Predicate Pushdown: WHERE clause filters run in the remote region, before the data moves. A 100M-row table filtered to 100 rows transfers 100 rows — not 100M.
Projection Pushdown: Only the columns named in SELECT are read from remote storage. BigQuery's columnar storage (Capacitor) makes this efficient.
Aggregation Pushdown: GROUP BY/SUM/COUNT operations run as partial aggregations in the remote region. A billion-row transaction table can be summarized to 365 rows (daily totals) before transfer.

3. Data Transfer

Filtered, minimized results travel over Google's internal network to the Primary Region, where they're stored in temporary internal tables for up to 8 hours. This is where cross-region egress charges are incurred.

4. Final Join

The Primary Region merges local data with the temporary remote data, as if everything were in one place. The query result returned to the user looks like any normal BigQuery result.

-- Executed from asia-northeast1 (Tokyo)
SELECT
  t1.product_id,
  t1.sales + t2.sales AS total_global_sales
FROM `project.japan_dataset.sales` AS t1   -- local
JOIN `project.us_dataset.sales` AS t2      -- remote (auto-transferred)
ON t1.product_id = t2.product_id
WHERE t1.date = '2026-03-01'               -- pushed down to both regions

IAM Permissions

Global Queries require two layers of setup.

Project-level opt-in (admin task)

-- Enable execution from the primary region
ALTER PROJECT `your-project-id`
SET OPTIONS (
  `region-asia-northeast1.enable_global_queries_execution` = true
);

-- Enable data access from the remote region
ALTER PROJECT `your-project-id`
SET OPTIONS (
  `region-us-central1.enable_global_queries_data_access` = true
);

User-level permissions

Role	Description
`bigquery.jobs.createGlobalQuery`	Required to initiate a global query. Currently only included in `roles/bigquery.admin` — create a custom role for regular users.
`roles/bigquery.dataViewer`	Required on every dataset being referenced, in every region.

Cost Structure

Global queries have three billing components instead of the usual one:

Component	Details	Approximate Price (2026)
Compute	Bytes scanned across all regions	$6.25 / 1 TB (on-demand)
Egress	Data transferred from remote to primary region	~$0.08–$0.12 / 1 GB (intercontinental)
Temporary Storage	Intermediate data stored for up to 8 hours	~$0.02/GB-month (prorated)

Cost simulation

Scenario: Query from Tokyo, scanning a 1 TB table in us-central1, with a WHERE clause that reduces the data transferred to 1 GB.

Compute: 1 TB × $6.25 = $6.25
Egress: 1 GB × $0.12 = $0.12
Total: ~$6.37

If you skip the WHERE clause and transfer the full 1 TB: egress alone exceeds $100. Pushdown is not optional — it's the entire cost model.

Dry run before executing

Use the BigQuery Console (it shows estimated bytes scanned before you click Run) or the CLI:

bq query --dry_run --use_legacy_sql=false 'SELECT ...'

Note: As of the current preview, dry runs may not accurately estimate egress (only compute bytes). Budget conservatively.

Key Considerations

Latency

Cross-region queries are always slower than single-region queries. Physical distance adds hundreds of milliseconds of network latency, plus multi-region orchestration overhead. Expect a minimum of 5–10 seconds even for modest cross-region joins. Real-time dashboards are not a good fit.

Data Residency

The Primary Region is where remote data lands temporarily. If GDPR or local privacy laws prohibit data from Region A leaving Region A, you must run the query from Region A as the primary — not from a region outside it. VPC Service Controls perimeters are also respected.

Current Limitations (Preview, March 2026)

No Query Cache

Global queries never use the query cache. Since data can change in any remote region at any time, BigQuery always reads fresh data. Every execution incurs full compute and egress costs.

Workaround: For frequently-used cross-region joins, materialize results into a local table using CREATE TABLE AS SELECT and query that instead.

No INFORMATION_SCHEMA from Remote Regions

You cannot query INFORMATION_SCHEMA views from a remote region within a global query. Joining metadata across regions requires first exporting that metadata into regular tables.

Unsupported Table Types

BigLake Apache Iceberg tables in remote regions are not supported as remote sources.
Partition pseudo-columns (_PARTITIONTIME, _PARTITIONDATE) may not pushdown correctly (more on this below).

No Sandbox Support

Billing Account required. The Sandbox (free tier) does not support Global Queries because egress charges can exceed the free quota.

The Partition Pseudo-Column Trap

This is the most dangerous limitation in production, and deserves its own section.

Background: Pseudo-columns vs. Physical columns

BigQuery offers two partitioning strategies:

Type	Partition Key	Access
Ingestion-time partitioned	Arrival timestamp, managed by BigQuery	Via `_PARTITIONTIME` / `_PARTITIONDATE` (pseudo-columns)
Column-based partitioned	An actual column in your table schema (e.g., `event_date`)	Via the column name directly

Pseudo-columns are not part of the formal table schema. They're metadata-level constructs.

Why pushdown fails for pseudo-columns

When the Query Optimizer sends execution instructions to a remote region, it works from the table's schema definition. Pseudo-columns aren't in that definition, so the optimizer can't reliably communicate partition pruning constraints to the remote worker.

Worst case: A filter like WHERE _PARTITIONDATE = '2026-03-01' is silently ignored in the remote region. The remote worker scans the entire table across all partitions and begins transferring everything to the primary region. Your query either times out or generates a very large bill.

The fix: Migrate to column-based partitioning

-- Create a new table with an explicit physical partition column
CREATE TABLE `project.dataset.new_table`
PARTITION BY event_date
AS
SELECT
  *,
  CAST(_PARTITIONDATE AS DATE) AS event_date  -- materialize the pseudo-column
FROM `project.dataset.old_table`

With a physical column, the optimizer sees it in the schema, understands the partition structure, and confidently applies pushdown in the remote region.

Workaround B: Aliasing via Views (use with caution)

If migrating the table isn't possible, you can create a view in the remote region that aliases the pseudo-column:

-- View in us-central1
CREATE VIEW `project.us_dataset.v_sales` AS
SELECT
  *,
  _PARTITIONDATE AS partition_date_col
FROM `project.us_dataset.ingestion_time_partitioned_table`

Then query the view from the primary region:

SELECT * FROM `project.us_dataset.v_sales`
WHERE partition_date_col = '2026-03-01'

This sometimes works for simple queries, but pushdown is not guaranteed. In complex queries with JOINs or aggregations, the optimizer often loses the connection between the aliased column and the underlying partition structure, falls back to full-scan, and transfers everything.

Always verify that pushdown is working by checking the Query Execution Plan and confirming the remote READ stage shows filtered row counts — not the full table row count.

Operational Best Practices

Problem	Recommendation
No query cache	Materialize frequent cross-region joins into local intermediate tables
Need metadata across regions	Export metadata to regular tables on a schedule
Ingestion-time partitioned tables	Migrate to column-based partitioning before using as remote sources
Unclear cost pre-execution	Use dry run + estimate egress separately; add a buffer

Summary

BigQuery Global Queries is a genuinely useful feature that eliminates an entire category of ETL pipelines. The execution model is well-designed — pushdown at the predicate, projection, and aggregation levels means you're typically only transferring the data you actually need.

The key things to internalize:

Pushdown is the cost model. Filter early, select only the columns you need, push aggregations to the remote side.
Ingestion-time partitioned tables are a liability in global queries. Migrate to column-based partitioning.
It's Preview — no query cache, no INFORMATION_SCHEMA cross-region, no BigLake Iceberg remotes. Design your architecture around these constraints.

Check the official documentation for the latest changes as this feature moves toward GA.

The Cloud is No Longer Virtual: The Harsh Physical Reality of AI Infra in 2026

Hiroshi Toyama — Mon, 23 Feb 2026 08:42:02 +0000

TL;DR

The "Virtual" in Cloud is fading. In 2026, AI infrastructure is dominated by three physical constraints: power grid capacity, tax legislations, and liquid cooling. If you are still picking regions based solely on latency, you are overpaying by at least 20%.

1. The Death of the "Sales Tax Holiday"

For a decade, states like Virginia attracted data centers with massive sales tax exemptions. That era ended in February 2026 with Virginia HB 897.

Why this matters for your bill:

In the US, "Sales Tax" works differently from Japan's VAT or Europe's VAT. It is a sunken cost with no tax credit for businesses. When a state removes a 6-10% tax exemption on hardware:

An NVIDIA B200 cluster worth $100M suddenly costs $110M.
This extra Capex is directly passed to you as higher hourly instance rates.

The Move: We are seeing a "Great Migration" to the Midwest AI Belt (Indiana, Ohio, Iowa), where 20-30 year tax holidays are still guaranteed.

2. Why "Power" is the New "Latency"

We used to care about milliseconds. Now, we care about Megawatts.

The Virginia Gridlock

In North Virginia (us-east-1), data centers now consume over 25% of the total state power. The grid is saturated. To build new AI capacity, AWS and Google are now forced to become Energy Producers.

Nuclear is the New "Default Gateway"

SMRs (Small Modular Reactors): AWS is deploying SMRs as "Microservices for Energy"—factory-built reactors that can be dropped next to a data center.
Direct-to-Plant: Microsoft and Azure are restarting decommissioned plants (like Three Mile Island) just to keep their GPUs humming.

3. The "Jevons Paradox" of NVIDIA GPUs

People often ask: "Why doesn't NVIDIA make low-power GPUs?"

The answer is Tokens per Watt. NVIDIA's Blackwell (B200) consumes a massive 1,200W, but it is 25x more efficient at generating tokens than the previous generation.

The Thermal Wall

Because one rack now pulls 120kW+, traditional air cooling is dead. 2026 is the year of Liquid Cooling. If your DC doesn't have pipes, it can't run the latest AI models. This creates a "Performance Gap" between old regions and new AI-native regions.

4. The Tokyo Context: Why so expensive?

Many Japanese developers wonder why ap-northeast-1 costs more than us-east-1 despite Japan's "cheaper" cost of living.

Imported Energy: Japan's industrial electricity is 2-3x more expensive than the US.
Dollar-Denominated Silicon: Everything from the GPU to the fuel for the power plant is priced in USD. The weak Yen makes these "imported" cloud resources luxury items.
Humidity: Tokyo’s humid summers make PUE (Power Usage Effectiveness) worse than the dry, flat plains of Ohio.

5. FinOps 2026: Actions for Engineers

"Turning off idle instances" is FinOps 101. To be a Senior Infrastructure Engineer in 2026, you need Regional Arbitrage.

Move Training to the Midwest: Shift non-latency-sensitive training jobs from us-east-1 to us-west-2 (Oregon) or the new Indiana regions to save 10-15% on tax and power alone.
Use Token-Specific Hardware: Evaluate TPU v7 (Google Cloud) or Trainium 2 (AWS). In 2026, specialized ASICs are often 3x more cost-effective than general-purpose GPUs for specific LLM workloads.
Infrastructure as Code (IaC) for Regions: Don't hardcode regions. Use variables that allow you to follow the "Tax-Free Energy" across the globe.

Final Thoughts

The cloud is no longer an invisible layer of abstraction. It is a physical plant that breathes energy and exhales heat. The best engineers in 2026 will be those who understand the physics and economics behind the API call.

What are your thoughts? Are you planning to migrate your workloads out of Virginia? Let's discuss in the comments!

Track Your Azure OpenAI Costs in Seconds, Not Minutes

Hiroshi Toyama — Mon, 26 Jan 2026 12:32:19 +0000

If you're building AI applications with Azure OpenAI, you know the drill: costs can spiral fast. One experimental feature using o1-preview, a few hundred test runs, and suddenly your bill looks very different from last month.

The Azure portal shows you the numbers eventually, but when you're iterating quickly on AI features, you need real-time visibility. That's exactly what azurecost delivers - instant Azure OpenAI cost tracking from your terminal.

The Azure OpenAI Cost Challenge

Unlike traditional cloud services with predictable pricing, Azure OpenAI costs vary wildly based on:

Model choice (GPT-4o-mini vs o1-preview is a 5-15x difference)
Token usage (both prompt and completion tokens)
Deployment scaling and throughput
Testing and development cycles

The questions you need answered daily:

"How much did my o1-preview deployment cost yesterday?"
"Which resource group is burning through credits?"
"Did that new feature spike my OpenAI spend?"
"How does dev environment cost compare to production?"

Checking this through the Azure portal means multiple clicks, page loads, and waiting. When you're checking costs multiple times a day during active development, this friction adds up.

The Solution

azurecost is a Python CLI tool built specifically for developers who need fast answers about their Azure spending. For Azure OpenAI users, it's the fastest way to track Cognitive Services costs without touching the Azure portal.

Why It Works for Azure OpenAI

Instant visibility: See your OpenAI costs in 2 seconds, not 2 minutes
Daily granularity: Catch cost spikes the day they happen, not at month-end
Resource-level tracking: Monitor individual Azure OpenAI accounts separately
Resource group isolation: Separate dev, staging, and production costs effortlessly
Multi-dimensional views: Break down by service, location, resource group, or resource ID
Automation-ready: Python API for integrating into your CI/CD or daily reports
Auto-currency: Works with any billing currency

Getting Started

Installation takes one line:

pip install azurecost

az login

Check your Azure OpenAI costs:

azurecost -s your-subscription-name

Output looks like this:

(USD)                 2025-11    2025-12
------------------  ---------  ---------
total                 1247.83    2891.45
Cognitive Services    1247.83    2891.45

That's your Azure OpenAI spend right there - Cognitive Services is the billing category for Azure OpenAI. Notice the spike in December? Now you can investigate what changed.

Real-World Azure OpenAI Use Cases

Scenario 1: Daily Cost Monitoring During Development

You're building a new reasoning agent with o1-preview. Check costs every morning:

azurecost -s prod-subscription -g DAILY -a 7

Output:

(USD)           2025-12-15  2025-12-16  2025-12-17  2025-12-18
------------  -----------  -----------  -----------  -----------
total                45.23        52.18       178.45        51.20
Cognitive Services   45.23        52.18       178.45        51.20

Whoa, December 17th spiked to $178. That's the day you started load testing with o1-preview. Now you know exactly when and how much it costs.

Scenario 2: Environment-Based Cost Breakdown

You have separate resource groups for dev, staging, and production. See costs side by side:

azurecost -s ai-subscription -d ResourceGroup -d ServiceName

Output:

(USD)                                        2025-11    2025-12
-----------------------------------------  ---------  ---------
total                                        1247.83    2891.45
ai-dev-rg/Cognitive Services                  342.15     456.32
ai-staging-rg/Cognitive Services              198.42     287.89
ai-prod-rg/Cognitive Services                 707.26    2147.24

Production jumped from $707 to $2147. Time to optimize those prompts or consider GPT-4o-mini for some use cases.

Scenario 3: Focused Investigation on Production

Something's wrong with production costs. Drill down to just that resource group:

azurecost -s ai-subscription -r ai-prod-rg -g DAILY -a 14

See two weeks of daily costs for production only. Spot the pattern, correlate with deployments or feature releases.

Scenario 4: Multi-Region Cost Analysis

Running Azure OpenAI deployments in multiple regions? Group by location:

azurecost -s global-ai-sub -d Location -d ServiceName

Output:

(USD)                                   2025-11    2025-12
------------------------------------  ---------  ---------
total                                   1247.83    2891.45
East US/Cognitive Services               823.14    1923.87
West Europe/Cognitive Services           424.69     967.58

East US is handling most of the load. Maybe redistribute traffic or consider regional pricing differences.

Scenario 5: Resource-Level Cost Analysis

Running multiple Azure OpenAI accounts for different teams or use cases? Track costs at the individual resource level:

azurecost -s ai-subscription -d ResourceId

Output:

(USD)                                                                                     2025-12    2026-01
--------------------------------------------------------------------------------------  ---------  ---------
total                                                                                     5741.44   16571.60
/resourcegroups/ai/providers/microsoft.cognitiveservices/accounts/chatbot-prod           3401.80   16390.44
/resourcegroups/ai/providers/microsoft.cognitiveservices/accounts/analytics-engine       2194.17     131.82
/resourcegroups/ai/providers/microsoft.cognitiveservices/accounts/internal-tools          145.47      49.34

This shows exactly which Azure OpenAI account is consuming credits. Perfect for:

Cost attribution: Charge back costs to specific teams or projects
Identifying cost anomalies: Spot which deployment suddenly increased spend
Multi-tenant environments: Track costs per customer or tenant
Budget allocation: Distribute budget based on actual usage patterns

Combine with daily granularity to investigate when a specific resource started costing more:

azurecost -s ai-subscription -d ResourceId -g DAILY -a 7

Why This Matters for Azure OpenAI Users

Building with Azure OpenAI is different from traditional cloud infrastructure. With VMs or databases, costs are fairly predictable. But with modern language models like GPT-4o and o1-preview, costs depend on how users interact with your application:

Long conversations = more tokens = higher costs
Complex reasoning tasks = more input tokens
Detailed responses = more completion tokens
Testing and iteration = multiplied costs

During active development, you need to check costs frequently. Not once a month when the bill arrives, but daily or even multiple times a day.

The Azure portal workflow kills this feedback loop:

Open browser
Navigate to Azure portal (wait for load)
Find the right subscription
Click through to Cost Management
Configure time range and filters
Wait for data to render

By the time you see the numbers, you've burned 2-3 minutes. When you're doing this multiple times daily, the friction discourages you from checking at all.

Then you're surprised at month-end when the bill is 3x what you expected.

azurecost fixes this. Checking costs becomes as fast as checking git status:

azurecost -s ai-subscription -g DAILY -a 7

Two seconds. Real-time feedback. No context switching.

This speed changes behavior. When checking costs is instant, you actually do it. You catch issues early. You experiment with confidence because you're monitoring the impact.

The tool emerged from my own need while building AI features. I was spending too much time in the portal doing the same query repeatedly. I wanted something terminal-based that integrated into my development workflow.

What started as a personal script evolved into a proper tool that my team adopted, then others in the community found useful. The philosophy is simple: do one thing well - show Azure costs fast and clearly.

Automate Azure OpenAI Cost Monitoring

The Python API lets you integrate cost tracking into your workflows. Send daily Azure OpenAI cost reports to Slack:

from azurecost import Azurecost
import requests
import os

# Get yesterday's costs
core = Azurecost(
    debug=False,
    granularity="DAILY",
    dimensions=["ResourceGroup", "ServiceName"],
    subscription_name="ai-production"
)

total_results, results = core.get_usage(ago=7)
text = core.convert_tabulate(total_results, results)

# Send to Slack
webhook_url = os.getenv("SLACK_WEBHOOK_URL")
message = f"🤖 Azure OpenAI Cost Report (Last 7 Days)\n```
{% endraw %}
\n{text}\n
{% raw %}
```"
requests.post(webhook_url, json={"text": message})

Run this as a daily cron job or GitHub Action. Your team gets automatic cost visibility without anyone checking the portal.

Other use cases:

Budget alerts: Trigger warnings when daily costs exceed thresholds
Cost attribution: Track which team or feature is using OpenAI credits
Pre-deployment checks: Validate costs before promoting to production
Finance automation: Generate reports for accounting without manual exports

Configuration Tips for AI Workloads

Set environment variables to streamline your daily checks:

# Add to your ~/.zshrc or ~/.bashrc
export AZURE_SUBSCRIPTION_ID=your-ai-subscription-id
export AZURE_RESOURCE_GROUP=ai-prod-rg

Now run azurecost with no arguments:

azurecost -g DAILY -a 7

Create shell aliases for common queries:

# Daily OpenAI costs
alias aicosts='azurecost -s ai-subscription -g DAILY -a 7'

# Production environment only
alias prodcosts='azurecost -s ai-subscription -r ai-prod-rg -g DAILY -a 7'

# Compare all environments
alias envcosts='azurecost -s ai-subscription -d ResourceGroup'

# Resource-level breakdown
alias resourcecosts='azurecost -s ai-subscription -d ResourceId'

Type aicosts each morning as part of your routine. Takes 2 seconds, keeps you informed. Use resourcecosts when you need to drill down to individual Azure OpenAI accounts.

Best Practices for Azure OpenAI Cost Management

Based on using azurecost with AI workloads, here are patterns that work:

1. Daily morning check

azurecost -s ai-sub -g DAILY -a 7

Catch anomalies before they compound. One day of unexpected costs is manageable. A month is not.

2. Before and after feature releases

# Before deployment
azurecost -s ai-sub -r ai-prod-rg -g DAILY -a 3

# Deploy new feature

# After 24 hours
azurecost -s ai-sub -r ai-prod-rg -g DAILY -a 3

Measure the cost impact of new features. Make data-driven decisions about o1-preview vs GPT-4o-mini.

3. Set up automated alerts
Use the Python API to send daily reports. Don't rely on remembering to check manually.

4. Isolate environments
Use separate resource groups for dev, staging, production. Makes cost attribution trivial.

5. Monitor during load testing
Run azurecost before and after load tests. Understand your cost-per-request at scale before going live.

Start Tracking Your Azure OpenAI Costs Now

Install the tool:

pip install azurecost

Check your costs:

azurecost -s your-subscription -g DAILY -a 7

That's it. You now have instant visibility into your Azure OpenAI spending.

Check the GitHub repository for full documentation, API examples, and to report issues or contribute.

Building AI features is expensive enough. Don't let invisible costs surprise you. Make cost visibility effortless.

Quick Links

GitHub: toyama0919/azurecost
PyPI: azurecost
Python 3.8+ required

Building with Azure OpenAI? Drop a comment on how you're managing costs or share your use case. Always looking for feedback and ideas.

ty: The Blazingly Fast Python Type Checker from Astral (Ruff & uv Creators)

Hiroshi Toyama — Wed, 07 Jan 2026 04:44:52 +0000

ty: The Blazingly Fast Python Type Checker from Astral

Astral, the company behind popular Python tools like Ruff and uv, has released a new type checker called ty. Built in Rust, it promises to revolutionize Python type checking with incredible speed and powerful features.

Key Features

⚡ Blazingly Fast: 10-100x faster than mypy and Pyright
🔍 Rich Diagnostics: Detailed error messages with multi-file context
🧠 Smart Type Inference: Catches bugs even without type annotations
🎯 Advanced Type System: Intersection types, advanced narrowing, reachability analysis
🛠️ Language Server: Built-in support for IDE integration (VS Code extension available)

Installation

# Using uv (recommended)
uv tool install ty@latest

# Using pip
pip install ty

Basic Usage

# Check a file
ty check file.py

# Check directories
ty check src tests

# Verbose mode
ty check src --verbose

What Makes ty Special?

1. Speed That Matters

ty can type-check the entire Home Assistant project in ~2.19 seconds, compared to mypy's 45.66 seconds. That's over 20x faster!

For large codebases, this speed difference transforms the developer experience:

No more waiting for CI to finish
Instant feedback in your IDE
Practical to run on every save

2. Powerful Type Inference

Here's the magic: ty can find bugs even without type annotations. Let's look at some examples.

Real-World Bug Detection

Example 1: Type Mismatches

def add(x: int, y: int) -> int:
    return x + y

result: str = add(1, 2)  # Oops! Assigning int to str

ty's output:

error[invalid-assignment]: Object of type `int` is not assignable to `str`
 --> example.py:4:9
  |
4 | result: str = add(1, 2)
  |         ---   ^^^^^^^^^ Incompatible value of type `int`
  |         |
  |         Declared type

Example 2: Missing Attributes

class User:
    def __init__(self, name: str):
        self.name = name

    def get_email(self):
        return self.email  # email was never defined!

ty catches this:

error[unresolved-attribute]: Object of type `Self@get_email` has no attribute `email`
 --> example.py:6:16
  |
6 |         return self.email
  |                ^^^^^^^^^^

This works even for complex cases:

class DatabaseClient:
    def __init__(self, connection_string: str):
        self.connection = connect(connection_string)

    def query(self, sql: str):
        # Typo: should be .execute(), not .exec()
        return self.connection.exec(sql)

ty will warn you that .exec() doesn't exist on the connection object!

Example 3: Incorrect Function Arguments

numbers: list[int] = [1, 2, 3]
numbers.append("four")  # String in int list!

ty's error:

error[invalid-argument-type]: Argument to bound method `append` is incorrect
 --> example.py:2:16
  |
2 | numbers.append("four")
  |                ^^^^^^ Expected `int`, found `Literal["four"]`

Example 4: Null Safety

def process(value: str | None) -> int:
    return len(value)  # What if value is None?

ty spots the issue:

error[invalid-argument-type]: Expected `Sized`, found `str | None`
 --> example.py:2:16
  |
2 |     return len(value)
  |                ^^^^^
  |
info: Element `None` of this union is not assignable to `Sized`

Example 5: Implicit None Returns

def get_name(user_id: int) -> str:
    if user_id > 0:
        return "User"
    # Missing return statement - implicit None!

ty catches this too:

error[invalid-return-type]: Function can implicitly return `None`,
which is not assignable to return type `str`

Configuration

ty uses pyproject.toml for configuration:

[tool.ty]
[tool.ty.environment]
python-version = "3.10"

[tool.ty.src]
include = ["src/**/*.py", "tests/**/*.py"]
exclude = [".tox/**", "build/**", "dist/**"]

# Per-directory overrides
[[tool.ty.overrides]]
include = ["tests/**/*.py"]
[tool.ty.overrides.rules]
invalid-assignment = "ignore"  # More lenient for tests

CI/CD Integration

GitHub Actions

name: Type Check
on: [push, pull_request]

jobs:
  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v5
        with:
          python-version: '3.10'
      - name: Install dependencies
        run: pip install ty
      - name: Run type checker
        run: ty check src tests

tox Integration

[testenv:ty]
deps =
    ty
    -e .
commands =
    ty check src tests

pre-commit Hook

repos:
  - repo: local
    hooks:
      - id: ty
        name: ty type checker
        entry: ty check src tests
        language: system
        pass_filenames: false
        types: [python]

Editor Integration

VS Code

Install the "ty" extension from VS Code Marketplace
Enjoy automatic:
- Type checking as you type
- Inlay hints for inferred types
- Code actions and quick fixes
- Jump to definition with type awareness

ty vs mypy vs Pyright

Feature	ty	mypy	Pyright
Speed	⚡⚡⚡ Ultra-fast	🐢 Moderate	🚀 Fast
Language	Rust	Python	TypeScript
Error Messages	📝 Very detailed	📄 Standard	📝 Detailed
Type Inference	🧠 Powerful	📚 Standard	🧠 Powerful
Maturity	🆕 Beta	✅ Stable	✅ Stable
Diagnostics	🔍 Multi-file context	📊 Single-file	🔍 Cross-file
Language Server	✅ Built-in	⚠️ Via dmypy	✅ Built-in

Current Limitations

As of v0.0.9 (Beta):

Limited rule set: Main rules implemented, more coming in 2026
No strict mode yet: Won't complain about missing type annotations
Beta status: API may change before stable release

However, even in beta, ty is already catching real bugs and providing value in production codebases.

Getting Started with ty

Here's a practical workflow for adopting ty in your project:

Step 1: Install and Run

uv tool install ty@latest
ty check src

Step 2: Review Results

ty will show you actual bugs in your code, even without type annotations!

Step 3: Add to CI

# Add to your test script
tox -e ty

# Or run directly
ty check src tests

Step 4: Gradual Type Annotation

As you maintain your code, gradually add type annotations where it makes sense:

# Before
def calculate_total(items):
    return sum(item.price for item in items)

# After
def calculate_total(items: list[Item]) -> Decimal:
    return sum(item.price for item in items)

With annotations, ty becomes even more powerful!

Real-World Example: FastAPI Application

from fastapi import FastAPI, HTTPException

app = FastAPI()

class UserService:
    def __init__(self, db_url: str):
        self.db = connect_database(db_url)

    def get_user(self, user_id: int):
        user = self.db.query(User).filter(User.id == user_id).first()
        if user:
            return user
        # Bug: FastAPI expects HTTPException, but we're returning None!
        return None

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    service = UserService(DB_URL)
    user = service.get_user(user_id)
    # Bug: user could be None, but we're accessing .dict()
    return user.dict()

ty will catch both bugs:

get_user can return None, but FastAPI expects an exception or a valid user
user.dict() could fail if user is None

Performance Tips

Use file exclusion: Skip generated files and vendor directories
Enable caching: ty caches results for unchanged files
Parallel processing: ty automatically uses multiple cores
Incremental mode: In your editor, only changed files are re-checked

Roadmap

According to Astral, ty is targeting a stable 1.0 release in 2026, with plans for:

✅ More comprehensive rule coverage
✅ Strict mode (enforce type annotations)
✅ Better integration with popular frameworks
✅ Plugin system for custom rules
✅ Performance optimizations

Conclusion

ty represents the next evolution in Python type checking. Its combination of blazing speed, powerful inference, and excellent diagnostics makes it a compelling choice for Python developers.

While still in beta, ty is already proving valuable for catching real bugs and improving code quality. If you're using mypy or Pyright and frustrated by slow check times, ty is worth trying.

The Astral team has an excellent track record with Ruff and uv, and ty looks set to be another game-changer in the Python tooling ecosystem.

Resources

🌐 Official Website: astral.sh/ty
📚 Documentation: docs.astral.sh/ty
💻 GitHub: github.com/astral-sh/ty
💬 Discord: Astral Discord

Have you tried ty yet? What's your experience with Python type checkers? Let me know in the comments! 👇

Introducing azurecost: Azure Cost Management Made Simple

Hiroshi Toyama — Tue, 16 Dec 2025 12:35:15 +0000

If you've ever struggled to understand your Azure costs through the portal's cluttered interface, you're not alone. That's why I created azurecost - a straightforward command-line tool that gives you instant visibility into your Azure spending.

The Problem

Azure's Cost Management portal is powerful, but sometimes you just want quick answers:

"How much did I spend last month?"
"Which services are costing me the most?"
"What's the cost breakdown by resource group?"

Navigating through the Azure portal for these simple questions feels like overkill. You need something faster.

The Solution

azurecost is a Python CLI tool that brings Azure cost data directly to your terminal. No clicking through menus, no waiting for the portal to load - just type a command and get your answer.

Key Features

Simple by default: Just run azurecost and see your monthly costs by service
Flexible dimensions: Group costs by resource group, service name, location, or any combination
Multiple time ranges: View daily or monthly costs for any time period
Auto-currency detection: Displays costs in your subscription's billing currency
Python API: Use it programmatically in your scripts and automation

Getting Started

Installation is one line:

pip install azurecost

Make sure you're logged in with Azure CLI:

az login

Then run it:

azurecost -s my-subscription

You'll see something like this:

(JPY)                 2023-08    2023-09
------------------  ---------  ---------
total                  492.77      80.28
Cognitive Services     492.77      80.28
Bandwidth                0          0
Storage                  0          0

Clean, readable, instant.

Real-World Examples

Multi-dimensional Analysis

Want to see costs broken down by both resource group and service? Easy:

azurecost -s my-subscription -d ResourceGroup -d ServiceName

Daily Monitoring

Tracking costs during a migration or deployment? Switch to daily granularity:

azurecost -s my-subscription -g DAILY -a 7

This shows you the last 7 days of costs, broken down by day.

Focused Investigation

Need to check costs for a specific resource group?

azurecost -s my-subscription -r production-rg -a 3

Shows 3 months of costs for just that resource group.

Why I Built This

The idea for azurecost came from a recurring frustration in my daily work as a cloud engineer. Every morning, I wanted to do a quick cost check - nothing fancy, just a sanity check to make sure nothing was unexpectedly spiking. But this simple task meant:

Opening a browser
Navigating to the Azure portal (and waiting for it to load)
Finding the right subscription
Clicking through to Cost Management
Waiting for the cost analysis page to render
Configuring the time range and dimensions I wanted
Waiting again for the data to load

By the time I got my answer, 2-3 minutes had passed. Multiply that by every time someone on the team needed to check costs, and we're talking about hours of wasted time per week.

I realized I was doing the same exact query every time. I didn't need the portal's full power - I needed something as simple as running git status or docker ps. Something that gave me the information I needed in 2 seconds, not 2 minutes.

Then there were the times when I was SSH'd into a server or working in a restricted environment where opening a browser wasn't convenient. Or when I wanted to pipe cost data into a script for automated reporting. The portal simply wasn't designed for these workflows.

So I built azurecost. The goal was simple: make checking Azure costs feel as natural as any other command-line operation. No ceremony, no waiting, no clicking.

What started as a personal productivity hack turned into something my team adopted, then colleagues at other companies started using it, and eventually it made sense to release it as an open-source tool.

The philosophy behind azurecost is that most of the time, you don't need 100 different options and visualizations. You need a fast, reliable answer to a simple question. The tool does one thing well: show you your Azure costs quickly and clearly.

Using It in Your Scripts

The Python API makes it easy to integrate cost monitoring into your automation:

from azurecost import Azurecost

core = Azurecost(
    debug=False,
    granularity="DAILY",
    dimensions=["ServiceName", "ResourceGroup"],
    subscription_name="my-subscription"
)

total_results, results = core.get_usage(ago=7)
text = core.convert_tabulate(total_results, results)
print(text)

Perfect for:

Daily cost reports sent to Slack
Budget alerts in your CI/CD pipeline
Cost attribution in team dashboards
Custom reporting for finance teams

Configuration Tips

Set environment variables to avoid typing the same options repeatedly:

export AZURE_SUBSCRIPTION_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export AZURE_RESOURCE_GROUP=production-rg

Now just run azurecost with no arguments. It'll use your configured subscription and resource group automatically.

What's Next

The tool is actively maintained and open to contributions. Some ideas I'm exploring:

Cost anomaly detection
Budget tracking and alerts
Cost forecasting based on historical trends
Integration with other cloud providers

Try It Out

The tool is open source and available on PyPI. Give it a try:

pip install azurecost
azurecost -s your-subscription

Check out the GitHub repository for full documentation, examples, and to report issues or contribute.

Azure cost management doesn't have to be complicated. Sometimes the best tool is the simplest one.

Links

🔗 GitHub: toyama0919/azurecost
📦 PyPI: azurecost
🐍 Python: 3.8+

Have questions or feedback? Open an issue on GitHub or drop a comment below!

Auto-generate Pull Requests with Claude API and Shell Function

Hiroshi Toyama — Mon, 15 Dec 2025 12:01:39 +0000

Created git-pr-auto

I built a shell function that sends git diff to Claude to auto-generate Pull Request titles and descriptions. It includes practical features like automatic GitHub account switching and remote branch checking.

Key features:

Claude automatically generates PR title and body from git diff
Auto-detects master and main branches
Checks remote branch existence before proceeding
Automatic GitHub account switching (personal/work)
Language switching based on account type
Confirmation step before creating PR
Automatically opens PR in browser after creation

Why I Built This

Writing Pull Requests was tedious. I faced several challenges:

PR Creation Takes Too Much Time

Recalling changes to write a title
Organizing and describing changes
Formatting the description
These tasks took 5-10 minutes every time

Switching Between Multiple Accounts is Annoying

Using separate GitHub accounts for work and personal projects
Need to configure git config for each repository
GitHub CLI authentication needs switching too
Wrong settings lead to PRs from the wrong account

Inconsistent PR Quality

Descriptions become sloppy when tired
Information gets insufficient when rushed
Sometimes fail to accurately convey changes

git-pr-auto solves these issues. Claude API analyzes the diff and generates appropriate titles and descriptions. Automatic account switching prevents configuration mistakes.

Prerequisites

You need the following setup to use this function.

GitHub CLI

# macOS
brew install gh

# Authentication (personal)
gh auth login

# Authentication (work)
GH_HOST=github.example.com gh auth login

Claude CLI

# For macOS
brew install anthropic/claude/claude

# Authentication
claude auth

Check the official documentation for Claude CLI.

Environment Variables

# Add to .zshrc or .bashrc

# Pattern for personal account repositories (regex)
export GITHUB_PERSONAL_PATTERN="github.com/(your-username|your-org)"

# Work account settings
export GITHUB_WORK_USER="work.user@company.com"
export GITHUB_WORK_HOST="github.example.com"

Implementation

Here's the complete implementation.

git-pr-auto() {
  # Auto-configure account
  if ! git-auth-setup; then
    return 1
  fi

  # Check GitHub CLI authentication
  if ! gh auth status >/dev/null 2>&1; then
    echo "Error: GitHub CLI is not authenticated"
    if [ -n "$GH_HOST" ]; then
      echo "Please run: GH_HOST=$GH_HOST gh auth login"
    else
      echo "Please run: gh auth login"
    fi
    echo ""
    echo "Current directory: $(pwd)"
    echo "Remote URL: $(git remote get-url origin 2>/dev/null)"
    return 1
  fi

  # Get current branch
  CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)

  # Detect master or main branch
  if git branch -a | grep -q "^\s*master$\|^\s*\*\s*master$\|remotes/origin/master$"; then
    BASE_BRANCH=master
  elif git branch -a | grep -q "^\s*main$\|^\s*\*\s*main$\|remotes/origin/main$"; then
    BASE_BRANCH=main
  else
    echo "Error: Neither master nor main branch found"
    return 1
  fi

  # Error if current branch is base branch
  if [ "$CURRENT_BRANCH" = "$BASE_BRANCH" ]; then
    echo "Error: Cannot create PR from $BASE_BRANCH branch"
    return 1
  fi

  # Determine whether to use local or remote branch
  if git rev-parse --verify "$BASE_BRANCH" >/dev/null 2>&1; then
    COMPARE_BASE="$BASE_BRANCH"
  elif git rev-parse --verify "origin/$BASE_BRANCH" >/dev/null 2>&1; then
    COMPARE_BASE="origin/$BASE_BRANCH"
  else
    echo "Error: Cannot find $BASE_BRANCH branch locally or remotely"
    return 1
  fi

  echo "📊 Checking diff between $CURRENT_BRANCH and $COMPARE_BASE..."
  echo "----------------------------------------"

  # Get diff
  DIFF=$(git diff $COMPARE_BASE..HEAD)

  if [ -z "$DIFF" ]; then
    echo "Error: No differences found between $CURRENT_BRANCH and $COMPARE_BASE"
    return 1
  fi

  # Show diff summary
  echo "Files changed:"
  STAT_OUTPUT=$(git diff --stat $COMPARE_BASE..HEAD)
  if [ -z "$STAT_OUTPUT" ]; then
    echo "Error: No file changes detected"
    return 1
  fi
  echo "$STAT_OUTPUT"
  echo "----------------------------------------"

  # Check remote branch existence
  if ! git ls-remote --exit-code --heads origin "$CURRENT_BRANCH" >/dev/null 2>&1; then
    echo ""
    echo "❌ Error: Remote branch 'origin/$CURRENT_BRANCH' does not exist"
    echo ""
    echo "Please push your branch to remote first:"
    echo "  git push -u origin $CURRENT_BRANCH"
    return 1
  fi

  # Generate PR content with claude command
  echo "🤖 Analyzing diff with Claude..."

  # Change Body language based on account type
  if [ "$GITHUB_ACCOUNT_TYPE" = "personal" ]; then
    BODY_LANG="English"
  else
    BODY_LANG="Japanese"
  fi

  PR_CONTENT=$(claude -p "Generate a Pull Request title and description from the following git diff.

Please output in the following format only (do not output any other text):

TITLE: [Concise title (English, within 50 characters)]

BODY:
[Description of changes (in ${BODY_LANG} in detail)]
- Change 1
- Change 2
...

Below is the git diff:
$DIFF
")

  # Debug: Check Claude output
  if [ -z "$PR_CONTENT" ]; then
    echo "Error: Claude returned empty response"
    return 1
  fi

  # Extract title and body
  PR_TITLE=$(echo "$PR_CONTENT" | grep "^TITLE:" | head -n 1 | sed 's/^TITLE:[[:space:]]*//')
  PR_BODY=$(echo "$PR_CONTENT" | sed -n '/^BODY:/,$ p' | tail -n +2)

  # Error if title is empty
  if [ -z "$PR_TITLE" ]; then
    echo "Error: Failed to extract PR title from Claude response"
    echo "Claude output:"
    echo "$PR_CONTENT"
    return 1
  fi

  echo "----------------------------------------"
  echo "📝 Generated PR Content:"
  echo "Title: $PR_TITLE"
  echo ""
  echo "Body:"
  echo "$PR_BODY"
  echo "----------------------------------------"

  # Create PR
  echo ""
  read "?Create PR? (y/N): " CONFIRM
  if [ "$CONFIRM" = "y" ] || [ "$CONFIRM" = "Y" ]; then
    echo "🚀 Creating PR..."
    PR_URL=$(gh pr create --base "$BASE_BRANCH" --title "$PR_TITLE" --body "$PR_BODY" 2>&1 | grep -o 'https://github.com/[^[:space:]]*')

    if [ -n "$PR_URL" ]; then
      echo ""
      echo "✅ PR created successfully!"
      echo "Opening PR in browser..."
      open "$PR_URL"
    else
      echo ""
      echo "✅ PR created successfully!"
      gh pr view --web
    fi
  else
    echo "PR creation cancelled"
  fi
}

Key Points

1. Remote Branch Check

Before calling Claude API, it checks if the remote branch exists. This prevents wasting API costs and time.

if ! git ls-remote --exit-code --heads origin "$CURRENT_BRANCH" >/dev/null 2>&1; then
  echo "❌ Error: Remote branch 'origin/$CURRENT_BRANCH' does not exist"
  echo "Please push your branch to remote first:"
  echo "  git push -u origin $CURRENT_BRANCH"
  return 1
fi

2. Language Switching Based on Account Type

Generates PR body in English for personal accounts and Japanese for work accounts.

if [ "$GITHUB_ACCOUNT_TYPE" = "personal" ]; then
  BODY_LANG="English"
else
  BODY_LANG="Japanese"
fi

3. Prompt for Claude

Specifying a clear format for Claude ensures parseable output.

PR_CONTENT=$(claude -p "Generate a Pull Request title and description from the following git diff.

Please output in the following format only (do not output any other text):

TITLE: [Concise title (English, within 50 characters)]

BODY:
[Description of changes (in ${BODY_LANG} in detail)]
- Change 1
- Change 2
...

Below is the git diff:
$DIFF
")

Usage

Basic Usage

# Commit changes on feature branch
git add .
git commit -m "Add new feature"

# Push to remote
git push -u origin feature-branch

# Auto-create PR
git-pr-auto

The execution flow:

Automatic account configuration
GitHub CLI authentication check
Base branch detection
Diff verification and display
Remote branch check
PR content generation with Claude API
Review generated content
Confirm PR creation
Create PR and open in browser

Example Execution

$ git-pr-auto

📊 Checking diff between feature-branch and main...
----------------------------------------
Files changed:
 functions/git.sh | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)
----------------------------------------

🤖 Analyzing diff with Claude...
----------------------------------------
📝 Generated PR Content:
Title: Add remote branch check before PR creation

Body:
Added remote branch existence check for more robust PR creation flow.

Changes:
- Check remote branch existence before Claude API call
- Display appropriate error message and push command when branch doesn't exist
- Reduce API cost and time waste
----------------------------------------

Create PR? (y/N): y
🚀 Creating PR...

✅ PR created successfully!
Opening PR in browser...

Automatic GitHub Account Switching

This function calls another function called git-auth-setup to automatically configure accounts.

git-auth-setup() {
  # Get remote URL
  REMOTE_URL=$(git remote get-url origin 2>/dev/null)

  if [ -z "$REMOTE_URL" ]; then
    echo "Error: Not a git repository or no remote configured"
    return 1
  fi

  # Determine if personal or work account
  if echo "$REMOTE_URL" | grep -qE "$GITHUB_PERSONAL_PATTERN"; then
    # Personal account settings
    export GITHUB_ACCOUNT_TYPE="personal"
    unset GH_HOST
    git config user.name "Your Name"
    git config user.email "personal@example.com"
  else
    # Work account settings
    export GITHUB_ACCOUNT_TYPE="work"
    export GH_HOST="$GITHUB_WORK_HOST"
    git config user.name "Your Work Name"
    git config user.email "$GITHUB_WORK_USER"
  fi
}

This mechanism automatically switches to the appropriate account settings based on the repository URL.

Troubleshooting

Claude CLI Not Installed

command not found: claude

Install Claude CLI:

brew install anthropic/claude/claude
claude auth

GitHub CLI Not Authenticated

Error: GitHub CLI is not authenticated
Please run: gh auth login

Authenticate with the displayed command:

# Personal account
gh auth login

# Work account
GH_HOST=github.example.com gh auth login

Remote Branch Doesn't Exist

❌ Error: Remote branch 'origin/feature-branch' does not exist
Please push your branch to remote first:
  git push -u origin feature-branch

Push with the displayed command:

git push -u origin feature-branch

Empty Claude Response

Error: Claude returned empty response

Possible causes:

Claude API authentication expired → Re-authenticate with claude auth
Diff is too large → Split commits to make them smaller
Network issues → Check connection

Can't Extract PR Title

Error: Failed to extract PR title from Claude response

This occurs when Claude's output format differs from expectations. Check the debug output and adjust the prompt if needed.

Further Improvements

While the current implementation is practical, there's room for improvement:

Draft PR Support

gh pr create --draft --base "$BASE_BRANCH" --title "$PR_TITLE" --body "$PR_BODY"

Add an option to create as a draft PR.

Auto-assign Reviewers

gh pr create --base "$BASE_BRANCH" --title "$PR_TITLE" --body "$PR_BODY" \
  --reviewer "reviewer1,reviewer2"

Automatically assign team members as reviewers.

Auto-label

gh pr create --base "$BASE_BRANCH" --title "$PR_TITLE" --body "$PR_BODY" \
  --label "enhancement,needs-review"

Automatically add labels based on the changes.

Template Support

Read GitHub's PR template and pass it to Claude to generate PRs that follow the template.

Summary

git-pr-auto makes PR creation dramatically easier. It's particularly effective in these scenarios:

Managing multiple GitHub accounts
Finding PR descriptions tedious to write
Spending too much time organizing and summarizing changes
Wanting to automate the PR creation process

Claude API's accuracy is high, generating content that's usable as-is in most cases. Occasional adjustments are needed, but it's much faster than writing from scratch.

Since using this function, time spent on PR creation has significantly decreased. Give it a try if you face similar challenges.

References

Easy Deployment of Vertex AI Agent Engine with vaiae

Hiroshi Toyama — Sat, 29 Nov 2025 08:21:21 +0000

Introducing vaiae

https://github.com/toyama0919/vaiae

vaiae is a tool that makes it easy to deploy and manage Google Cloud Vertex AI Agent Engine from the command line. Define your configuration in a YAML file and deploy with a single command.

Key features:

Declarative deployment with YAML configuration files
Profile management for multiple environments (dev/prod, etc.)
Interactive messaging with AI Agents
Safe validation with dry run mode
Available as both a Python library and CLI

Why I Built This

Deploying and managing Vertex AI Agent Engine traditionally involved tedious manual work. There were several challenges:

Too Much Manual Work

Need to configure AI Agents through the GCP console every time
Complex dependency and package version management
Manual configuration of environment variables and secrets

Difficult Environment Management

Tedious to separate development and production environment settings
Need to manually switch between different configurations for each environment
No way to track configuration history or version control

Team Development Challenges

Need to document and share configuration details
Configuration drift between team members
Deployment procedures become person-dependent

vaiae solves these challenges with YAML-based configuration management and a simple CLI. Since configurations are managed as code, they can be version-controlled with Git and shared with the team. The profile feature also makes managing multiple environments easy.

This article covers everything from basic usage to practical applications of vaiae.

Installation

Easy installation with pip:

pip install vaiae

Python 3.10 or higher is required.

GCP Authentication Setup

Before using vaiae, you need to configure Google Cloud authentication:

# Using Application Default Credentials
gcloud auth application-default login

# Using service account key
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

Also, make sure the Vertex AI API is enabled.

Basic Usage

Creating a Configuration File

Create .agent-engine.yml in your project root. This is the Agent Engine definition file.

default:
  # Vertex AI configuration
  vertex_ai:
    project: "my-gcp-project"
    location: "asia-northeast1"
    staging_bucket: "my-staging-bucket"

  display_name: "my-agent-engine"
  description: "Basic Agent Engine"
  gcs_dir_name: "my-agent/1.0.0"

  # AI Agent configuration
  agent_engine:
    instance_path: "my_package.agents.main_agent"

  # Environment variables
  env_vars:
    API_KEY: "your-api-key"
    SLACK_WEBHOOK_URL:
      secret: "slack-webhook-url"
      version: "latest"

  # Dependencies
  requirements:
    - "google-cloud-aiplatform[adk,agent_engines]==1.96.0"
    - "google-adk"
    - "requests"

Important points:

display_name serves as a unique identifier for the Agent Engine
Redeploying with the same display_name will update instead of creating a new one
instance_path dynamically imports an existing AI Agent instance

Agent Implementation Example

Here's how to create an AI Agent using google-adk that can be referenced by instance_path:

# my_package/agents.py
from google.adk.agents import Agent

# Define tools as regular functions
def get_weather(location: str) -> str:
    """Get weather information for a location.

    Args:
        location: City name

    Returns:
        Weather information
    """
    return f"The weather in {location} is sunny, 22°C"

def calculate_sum(a: int, b: int) -> int:
    """Calculate the sum of two numbers.

    Args:
        a: First number
        b: Second number

    Returns:
        Sum of a and b
    """
    return a + b

# Create the root agent
main_agent = Agent(
    name="my_agent",
    model="gemini-2.0-flash-exp",
    description="A helpful assistant that can check weather and perform calculations.",
    instruction="""
    You are a helpful assistant with the following capabilities:
    - Check weather information using get_weather tool
    - Perform calculations using calculate_sum tool

    Always be polite and provide clear responses.
    """,
    tools=[get_weather, calculate_sum],
)

This agent can be referenced in your .agent-engine.yml using:

agent_engine:
  instance_path: "my_package.agents.main_agent"

The instance_path points to the main_agent variable defined in the my_package.agents module. vaiae will dynamically import this agent instance when deploying.

For more complex agent examples, refer to the Vertex AI documentation and google-adk PyPI package.

Deployment

Once you've created the configuration file, deployment is simple:

# Preview with dry run
vaiae deploy --dry-run

# Actually deploy
vaiae deploy

Using dry run lets you verify the configuration before actually deploying. This is especially important in production environments.

Checking Deployed AI Agents

You can list deployed Agent Engines:

vaiae list

Results are displayed in an easy-to-read table format:

Found 2 agent engine(s):

Display Name         Resource Name                                        Create Time                  Update Time
-------------------  ---------------------------------------------------  ---------------------------  ---------------------------
my-agent-dev         projects/.../agentEngines/123...                     2024-11-20 10:30:00          2024-11-25 14:20:00
my-agent-prod        projects/.../agentEngines/456...                     2024-11-15 09:00:00          2024-11-26 16:45:00

Sending Messages to AI Agents

You can interact with your deployed AI Agents:

# Basic message sending
vaiae send -m "Please analyze the data"

# Continue conversation with session ID
vaiae send -m "What's the next step?" -s "session-123"

# Specify user ID
vaiae send -m "Create a report" -u "user-456"

Using session IDs allows you to continue conversations while maintaining context from previous interactions.

Deleting AI Agents

You can delete Agent Engines when they're no longer needed:

# Verify with dry run
vaiae delete --dry-run

# Actually delete
vaiae delete

# Delete by name
vaiae delete -n "my-agent-engine"

# Force delete (including child resources)
vaiae delete -n "my-agent-engine" --force

Practical Usage

Managing Multiple Environments

Using different configurations for development and production is essential in real development. vaiae accomplishes this with profile functionality.

# Default configuration (common settings)
default:
  vertex_ai:
    location: "asia-northeast1"
    staging_bucket: "common-staging-bucket"

  agent_engine:
    instance_path: "my_package.agents.main_agent"

  requirements:
    - "google-cloud-aiplatform[adk,agent_engines]==1.96.0"
    - "google-adk"

# Development environment
development:
  vertex_ai:
    project: "dev-project"
  display_name: "my-agent-dev"
  description: "Development environment AI Agent"
  env_vars:
    DEBUG_MODE: "true"
    API_ENDPOINT: "https://api-dev.example.com"

# Production environment
production:
  vertex_ai:
    project: "prod-project"
  display_name: "my-agent-prod"
  description: "Production environment AI Agent"
  env_vars:
    DEBUG_MODE: "false"
    API_ENDPOINT: "https://api.example.com"

Deploy with specific profiles:

# Deploy to development environment
vaiae --profile development deploy

# Deploy to production environment
vaiae --profile production deploy

# Delete development AI Agent
vaiae --profile development delete

Using profiles makes it easy to switch between different project IDs, display_names, and environment variables per environment. It's efficient to write common settings in default and only override differences in each environment.

Debug Mode

When issues occur, you can check detailed logs with debug mode:

vaiae --debug deploy

Detailed logging makes it easier to identify problems.

Using Custom Configuration Files

To use a configuration file other than the default .agent-engine.yml:

vaiae --yaml-file custom-config.yml deploy

This is useful when you want different configuration files per project.

Using as a Python API

You can use vaiae not just as a CLI, but also from Python code. This is useful for integrating with CI/CD pipelines or for more complex automation.

Basic Usage

from vaiae.core import Core

# Initialize Core instance
core = Core(
    yaml_file_path=".agent-engine.yml",
    profile="default"
)

# Deploy
core.create_or_update_from_yaml(dry_run=False)

# Send message
response = core.send_message(
    message="Please run the analysis",
    user_id="user123"
)

Overriding Configuration

You can partially override YAML configuration. This is useful when you want to dynamically change settings.

from vaiae.core import Core

core = Core(yaml_file_path=".agent-engine.yml", profile="development")

# Partially override YAML configuration
core.create_or_update_from_yaml(
    dry_run=False,
    description="Dynamically generated description",
    env_vars={
        "CUSTOM_VAR": "custom_value",
        "API_ENDPOINT": "https://api.example.com"
    },
    requirements=["additional-package==1.0.0"]
)

Managing Agent Engines

from vaiae.core import Core

core = Core(yaml_file_path=".agent-engine.yml", profile="default")

# List agent engines
agent_engines = core.list_agent_engine()
for engine in agent_engines:
    print(f"Name: {engine.display_name}")
    print(f"Resource: {engine.resource_name}")

# Delete
core.delete_agent_engine_from_yaml(
    force=False,
    dry_run=False
)

Integrating with CI/CD Pipelines

Example of integrating with CI/CD pipelines like GitHub Actions or Cloud Build:

import os
from vaiae.core import Core

def deploy_agent():
    """Deploy by reading configuration from environment variables"""
    env = os.environ.get("DEPLOY_ENV", "development")

    core = Core(
        yaml_file_path=".agent-engine.yml",
        profile=env,
        debug=True
    )

    # Validate before deployment
    core.create_or_update_from_yaml(dry_run=True)

    # Actually deploy
    core.create_or_update_from_yaml(dry_run=False)
    print(f"Successfully deployed to {env} environment")

if __name__ == "__main__":
    deploy_agent()

Troubleshooting

Authentication Error

Error: Could not automatically determine credentials

This occurs when GCP authentication is not configured. Set up authentication with the following command:

gcloud auth application-default login

Or use a service account key:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

Permission Error

Error: Permission denied

The service account or user being used needs the following permissions:

aiplatform.agentEngines.create
aiplatform.agentEngines.update
aiplatform.agentEngines.delete
aiplatform.agentEngines.list

Grant the appropriate permissions in the GCP IAM console.

YAML Configuration Error

Error: Invalid YAML configuration

Check the YAML file syntax:

Is indentation correct (consistent with 2 or 4 spaces)?
Are all required fields configured?
Are special characters escaped?

Conclusion

With vaiae, deploying and managing Vertex AI Agent Engine becomes dramatically easier. Managing configurations with YAML files and easily switching between multiple environments is a huge advantage.

Main use cases:

Separate management of development and production environments
Integration with CI/CD pipelines
Sharing AI Agent configurations within teams
Version control and rollback

In particular, combining the profile feature with dry run enables safe and efficient deployment.

vaiae has more features planned for the future. I recommend checking the GitHub repository for the latest information.

Forem: Hiroshi Toyama

Managing AI Agent Skills with `npx skills`: A Practical Guide

The Problem

How It Works

GitHub as the Registry

SKILL.md as the Package Entry Point

.skills.json + skills-lock.json = package.json + package-lock.json

Key Commands

Gotchas

remove Doesn't Update the Lock File

experimental_ Prefix is Real

Cache Behavior with npx

CI/CD Integration

Creating Your Own Skill

Summary

Deploying a Google ADK Agent to Vertex AI Agent Engine with Terraform

Prerequisites

How Agent Engine Deployment Works

The Agent Entrypoint

Building the Source Archive

Terraform Configuration

provider.tf

Wiring the Archive Build

The Agent Engine Resource

Block Reference

class_methods in Detail

Gotchas

Deploy and Verify

Summary

AI-Driven Chrome Extension Development with WXT and Chrome DevTools MCP

The Problem

The Stack

Step 1: WXT with a Fixed CDP Port

Step 2: Chrome DevTools MCP Configuration

Step 3: The Dev Script (Optional but Recommended)

The Workflow in Practice

1. Start the environment

2. AI inspects current state

3. AI verifies changes through the browser

Tips and Gotchas

Content Script Isolation

Selector Strategy for Third-Party UIs

Async DOM Waiting

Google Login Gotcha

--user-data-dir and Security

Getting Started

1. Create a WXT project

2. Add CDP port to wxt.config.ts

3. Create .cursor/mcp.json

4. Run

Why This Workflow Matters

BigQuery Global Queries: Join Data Across Regions Without ETL

The Old Problem

How It Works: 4-Stage Execution

1. Distributed Execution

2. Data Pushdown

3. Data Transfer

4. Final Join

IAM Permissions

Project-level opt-in (admin task)

User-level permissions

Cost Structure

Cost simulation

Dry run before executing

Key Considerations

Latency

Data Residency

Current Limitations (Preview, March 2026)

No Query Cache

No INFORMATION_SCHEMA from Remote Regions

Unsupported Table Types

No Sandbox Support

The Partition Pseudo-Column Trap

Background: Pseudo-columns vs. Physical columns

Why pushdown fails for pseudo-columns

The fix: Migrate to column-based partitioning

Workaround B: Aliasing via Views (use with caution)

Operational Best Practices

Summary

The Cloud is No Longer Virtual: The Harsh Physical Reality of AI Infra in 2026

`remove` Doesn't Update the Lock File

`experimental_` Prefix is Real

`provider.tf`

`class_methods` in Detail

`--user-data-dir` and Security

2. Add CDP port to `wxt.config.ts`

3. Create `.cursor/mcp.json`