How to Use Gemini 4 Argon to Optimize a Large Python Codebase

Learn a practical, test-first workflow for using Gemini 4 Argon to find Python performance bottlenecks, benchmark changes, guide an AI coding agent, and review its pull request safely.

A coding assistant can explain a function or generate a small feature in minutes. Improving a mature Python codebase is a different challenge. Performance bottlenecks often cross module boundaries, and a change that makes one benchmark faster can still break compatibility, tests, or real workloads.

Google published a useful case study on October 13, 2026: its engineers used Gemini 4 Argon with Google Antigravity to investigate performance in the open-source Agent Development Kit for Python (ADK). The repository contained roughly 205,000 lines of code across nearly 800 source files and almost 17,000 unit tests. In an overnight run lasting about 11 hours, the agent proposed six optimizations. After review, two were retained: one reduced in-memory session-preparation overhead by about 40% in long sessions, and another reduced cold package-import time by 21%. Four other proposals were rejected because their trade-offs were not acceptable.

Those figures describe Google’s specific project and test setup, not a performance guarantee for your application. The more reusable lesson is the workflow: define a measurable goal, give the agent repository-specific engineering rules, establish a baseline, let it investigate broadly, and require human review before changes ship.

This guide turns that case study into a cautious, repeatable process you can adapt to your own Python project.

What You Need Before Starting

Prepare the project before asking an agent to optimize it. You should have:

A clean Git working tree and a dedicated branch for the experiment.
A reproducible way to install the project and run its tests.
At least one benchmark that represents a real user-facing or operational workload.
A known-good baseline, including the exact command, environment, and results.
A clear list of compatibility requirements and files or APIs that must not change.
A review process that prevents generated changes from being merged automatically.

Use a local checkout or an isolated worktree rather than experimenting directly on a production branch. Make sure you can return to the original state. If the repository contains customer data, credentials, private configuration, or proprietary code, check your organization’s policies before sending any of it to an AI service.

Gemini 4 Argon is available through Google’s developer platforms for eligible users. Google identifies the model ID as gemini-4-argon for API use, but this guide focuses on an agent-driven engineering workflow in Google Antigravity rather than API setup. If you first need to configure programmatic access, see our guide to using the Gemini 4 Argon API.

Step 1: Choose a Performance Goal You Can Measure

Avoid vague requests such as “make this code faster.” They give the agent too much freedom and make the result difficult to evaluate. Choose one or two measurable outcomes instead.

Useful goals include:

Reduce the median time needed to load a common object or session.
Reduce cold-start or package-import time.
Lower memory allocation during a representative operation.
Improve throughput for a fixed workload without changing output.
Reduce repeated serialization, copying, or initialization overhead.

Write down the workload and the acceptance criteria before the agent starts. For example:

Investigate the startup and repeated-session overhead in this Python service. First establish a reproducible baseline. Preserve public APIs, output semantics, and supported Python versions. Propose the smallest changes that improve the measured workload. Every accepted change must have a regression test and before-and-after benchmark results. Do not merge or deploy anything.

This prompt establishes constraints but does not tell the model which implementation to change. That is intentional: the agent should investigate first rather than jumping to a convenient but unverified fix.

A good target also includes a guardrail. “Reduce median request preparation time by 10% without changing output or increasing peak memory materially” is more useful than “make it faster.” Do not choose a percentage merely because it sounds ambitious; set the threshold after understanding the current performance and measurement noise.

Step 2: Capture a Baseline Before Editing

A benchmark is only useful when you can compare like with like. Record the Python version, operating system, dependency versions, hardware or CI runner, relevant environment variables, and exact command. Run the benchmark more than once and record the median or another appropriate statistic instead of relying on one unusually fast result.

For example, if the project uses pytest and has a benchmark suite, a baseline might be recorded like this:

python --version
python -m pip freeze > baseline-requirements.txt
python -m pytest

This is an illustrative starting point, not a universal performance benchmark. A passing test suite tells you about correctness coverage; it does not, by itself, measure speed. Use the project’s actual benchmark command, profiler, or a small repeatable harness that isolates the operation you want to improve.

For a short function, a microbenchmark may help identify a local cost. For a web service or agent framework, measure a representative end-to-end workflow as well. A change that improves an isolated function may not improve the complete request because network latency, model latency, storage, or other components dominate the total.

Keep a simple results table:

Measurement	Before	After	Notes
Median target-operation time	Record value	Record value	Same workload and environment
Cold package import	Record value	Record value	Fresh process each run
Peak memory	Record value	Record value	Same input size
Regression tests	Pass/fail	Pass/fail	Record the exact command

Do not fill the table with estimated improvements. Leave a result marked “not measured” until you have actual output. If the baseline varies widely, investigate the noise before trusting small differences.

Step 3: Give the Agent the Repository’s Engineering Rules

One important lesson from Google’s ADK experiment was that repository conventions matter. In its first run, Argon found potential performance improvements but did not know enough about the maintainers’ expectations. It made a change that subtly affected a public JSON schema, missed edge cases around test mocks, ran only a subset of the tests, and omitted benchmark numbers from the pull request description.

For the second run, the team placed maintainer guidance in a .agents/skills directory. The guidance was organized into short skill indexes and focused reference files, covering conventions such as private-module visibility and lazy-import expectations. This gave the agent relevant instructions without requiring every detail to be pasted into every prompt.

You can adapt the same idea. Put project-specific instructions in the location supported by your chosen agent and keep the guidance concise, accurate, and maintained alongside the code. Include topics such as:

Public APIs and compatibility promises that must remain stable.
Required test commands and any slow or integration test suites.
Import conventions and dependency boundaries.
Rules for private modules, generated files, and migration scripts.
Supported Python versions and platforms.
Performance measurement conventions and acceptable trade-offs.
Security restrictions, including commands or data the agent must not access.

Do not invent a SKILL.md format and assume every coding tool will automatically read it. Check the current documentation for the agent you use and confirm the instructions were actually loaded. In Google’s example, the repository’s .agents/skills files were part of the Antigravity workflow; other tools may use different instruction files or configuration.

A useful instruction should explain the reason behind a constraint. “Do not remove this import” is less helpful than “This symbol is patched by downstream tests and is part of the supported module surface; preserve access even if the implementation is loaded lazily.” Context helps the agent reason about alternatives instead of simply following a brittle prohibition.

Step 4: Ask for Investigation Before Asking for a Rewrite

Start with a read-only investigation. Ask the agent to map the relevant execution path, identify likely sources of overhead, and propose a measurement plan. Require it to distinguish evidence from hypotheses.

For example:

Inspect the repository and identify up to five plausible sources of overhead in the target workflow. Do not edit files. For each candidate, show the relevant modules or functions, explain why it may matter, identify what measurement would confirm it, and list risks to compatibility or correctness. Do not claim a bottleneck is proven until the benchmark or profiler supports it.

Review the findings yourself. Check whether the cited functions exist, whether the described code path is actually used, and whether the proposed benchmark measures the symptom. If the model cannot identify a concrete way to verify a claim, treat it as a hypothesis rather than a reason to change code.

This investigation-first approach also reduces wasted effort. It is easy for a model to produce a plausible cache, index, or custom copy routine before proving that the operation is expensive. In mature software, every new mechanism can introduce invalidation bugs, hidden state, maintenance burden, and compatibility problems. Prefer a demonstrated bottleneck over an elegant-sounding optimization.

Step 5: Use a Long-Running Goal Carefully

Google’s published example used the /goal mode in Antigravity to keep the objective in view across a long autonomous run. The agent worked overnight, read the repository guidance, measured multiple workloads, made changes, reran tests, and prepared a pull request for review.

If your current Antigravity version and account support a comparable goal-based workflow, express the goal and constraints once, then confirm the tool preserves them throughout the run. Feature availability and interface details can change, so consult the current Antigravity documentation rather than assuming every user sees the same controls.

A bounded goal might read:

Improve the measured startup overhead in this repository while preserving public behavior. Read the repository’s engineering guidance first. Establish a baseline before editing. Work only on the dedicated branch. For each proposed change, explain the measured benefit, correctness risks, and tests required. Run the agreed test suite and repeat the benchmark. Open a pull request with before-and-after results. Do not merge, deploy, alter credentials, or perform destructive actions.

For a long run, use practical limits. Set a maximum scope, avoid granting broad write access to unrelated systems, and require the agent to stop if the baseline cannot be reproduced or a test fails unexpectedly. A long-running agent should not be treated as an unsupervised maintainer. It can explore while you retain control over permissions, acceptance criteria, and final approval.

If you are new to task-oriented Gemini workflows, our guide to using Gemini 4 Argon for multi-step tasks in the Gemini app covers a different user-facing workflow. The engineering process here is specifically about source code, benchmarks, tests, and pull-request review.

Step 6: Evaluate the Patch, Not the Agent’s Confidence

Google reported six proposed optimizations in its overnight run, but only two were accepted. The rejected changes are just as instructive as the improvements that shipped. One cache appeared to improve a synthetic benchmark by 17% but depended on a fragile memory reference that could return stale data in an edge case. Another proposal accessed a private telemetry implementation detail that might change across dependency versions. Other changes added complexity without improving the independent end-to-end benchmark.

Use a review checklist for every candidate change:

Is the performance gain measured? Ask for the exact command, workload, number of runs, and before-and-after values.
Does the improvement survive an independent test? Re-run a representative benchmark that was not tailored solely to the proposed implementation.
Are outputs and public behavior unchanged? Compare return values, schemas, exceptions, ordering, and other observable behavior.
Does the change add fragile state? Examine caches, weak references, global variables, invalidation rules, and hidden coupling.
Does it depend on private library internals? Check whether the dependency explicitly supports the API being used.
Is the code still understandable? A tiny benchmark gain may not justify a complex path that future maintainers cannot safely modify.
Are the tests meaningful? Verify that new tests fail for the old bug and pass for the corrected behavior.

A benchmark improvement is not enough on its own. Reject a change when its benefit is too small, unstable, or limited to an artificial workload. Also reject changes that break public behavior even if a performance graph looks better.

Step 7: Run the Full Required Tests and Rebenchmark

After you approve a patch for further evaluation, run the relevant focused tests first. Then run the full test suite required by the project, including integration or compatibility tests that may exercise code outside the files changed by the agent.

Google’s report describes a useful warning: all 16,892 open-source tests passed in one stage, yet 25 internal Google test targets failed because those tests patched attributes that the proposed import changes had removed from their expected locations. The final approach preserved the required module access while deferring heavy imports. The lesson is not that every project needs Google’s internal tests; it is that a test suite can be extensive and still miss important downstream contracts.

When a test fails, do not ask the agent to keep making edits until the suite turns green without understanding the failure. Determine whether the failure exposes a real regression, a flaky test, an environment problem, or an unrelated pre-existing issue. Record the exact failure and require a justified fix.

Then rerun the original benchmark using the same environment and workload as the baseline. Measure the end-to-end result as well as the targeted operation. In Google’s example, package import time improved by 21%, but time from a fresh process to its first model request remained essentially flat because deferred modules still loaded on the first turn. That distinction matters: optimizing one stage may move work to another stage rather than eliminate it.

Report both wins and non-wins. If a change speeds up import time but makes the first real request slower, the trade-off should be visible. If a benchmark does not improve outside a synthetic test, say so plainly.

Step 8: Produce a Review-Ready Pull Request

The agent’s final output should make it easy for a human to decide whether to merge. Require a pull request description with:

The original performance problem and how it was measured.
The exact benchmark commands and environment.
Before-and-after results, including variability where relevant.
A summary of each changed file and why it changed.
Tests that actually ran and their outcomes.
Tests that could not be run, with the reason.
Compatibility, security, and maintenance risks.
Any trade-offs or regressions found during review.

Inspect the diff yourself rather than relying on the summary. Verify that generated files, dependency changes, configuration edits, and unrelated refactors are necessary. Confirm that the branch contains only the intended work. Require a human reviewer to approve the change and let the repository’s normal CI and branch protections run.

Do not permit the agent to merge its own pull request simply because it reports success. The purpose of delegation is to expand investigation and implementation capacity, not to remove accountability.

A Practical Acceptance Checklist

Before accepting any AI-generated performance optimization, confirm all of the following:

If one of the critical checks is missing, keep the patch in review rather than treating the task as complete.

What Google’s Results Do—and Do Not—Show

The ADK case study is useful because it describes a real repository, concrete measurements, and rejected proposals as well as accepted ones. Google reported roughly 40% less in-memory session-preparation overhead in long sessions and 21% faster cold package imports. In a 158-turn workload, the reported end-to-end run fell from 65.6 seconds to 56.1 seconds. These measurements isolate framework overhead under the study’s test conditions; they do not mean every application’s total response time will improve by the same amount.

The result also does not prove that Gemini 4 Argon is always the best coding model, that unattended work is safe in every repository, or that adding repository instructions guarantees correct code. The gains depended on the particular ADK architecture, workload, tests, and code-review decisions. Your project may have a different bottleneck—or no worthwhile optimization at all.

The transferable principle is to evaluate the whole engineering loop. Let the agent search across files and propose changes, but ground decisions in reproducible measurements, regression tests, compatibility requirements, and human judgment.

Frequently Asked Questions

Can Gemini 4 Argon optimize any Python project automatically?

No. It can assist with investigation and implementation, but the quality of the result depends on the repository, instructions, benchmark, tests, tool permissions, and review process. Some projects will not have a meaningful bottleneck that an AI-generated change can safely fix.

Do I need 17,000 tests like Google’s ADK project?

No. Use the tests and checks appropriate to your own project. The important point is to identify the required tests before editing and understand what they cover. A smaller project should still test the affected behavior and run its relevant regression suite.

Should I accept a change that improves a microbenchmark?

Not automatically. Confirm that the workload is representative, the result is reproducible, and the change improves the behavior you actually care about. A microbenchmark win can be offset by extra complexity or a slower end-to-end workflow.

Is it safe to leave an AI coding agent running overnight?

Only within an appropriately controlled environment. Use an isolated branch or worktree, minimal permissions, explicit constraints, reproducible tests, and a human review gate. Do not grant unrestricted production access or automatic merge and deployment authority just to keep the task moving.

Where can I inspect Google’s actual changes?

Google linked the merged ADK change in its official case study. Review the ADK performance commit on GitHub alongside the original Google Developers Blog article. The commit and blog post provide more detail than a model-generated summary alone.

Conclusion

To use Gemini 4 Argon for Python performance work, start with a measurable problem, capture a baseline, give the agent the repository’s real engineering rules, and ask it to investigate before editing. Use a bounded long-running goal only if your environment supports it, then inspect every proposed optimization for correctness, compatibility, maintainability, and real benchmark impact.

The most important part is the review process. Google’s own experiment produced six candidates but retained only two after engineering review. Treat that as the model for a disciplined workflow: let the agent explore, measure the outcome independently, and ship only the changes that earn their place in the codebase.