Getting Started with the Google Antigravity Agent API: Interactions API, Tool Calls, and State Continuation

Antigravity appears in the rising query for “coding agent” on Google Trends in the US.

Google now provides a preview entrance to the Interactions API of Antigravity Agent, so “available in the IDE” and “called in the program” need to be understood separately.

What tasks is this API suitable for?

It is suitable for development tasks that have clear goals and require multi-step reasoning and tool operations.

For example, read the repository, locate errors, modify the code, and run tests.

Single-pass text completion does not require the use of the Agent runtime.

The preview version is also not suitable for direct operation of production environments without isolation.

Record four pieces of information before starting

Google AI Studio project.
The project to which the API key belongs.
Selected model and regional availability.
Quotas for free or paid tiers.

The key only puts environment variables:

1

$env:GEMINI_API_KEY = Read-Host "Gemini API key"

Don’t write real keys into sample scripts, screenshots, or Git history.

Make the minimum request without tools first

Use the SDK and field names currently shown in the official documentation.

The preview API changes quickly, so check the version before copying the old blog code.

Request the target to write only one acceptable action, such as “Explain this error and give two hypotheses.”

Save response ID, model name, time taken and usage.

The response ID is important evidence for subsequent connection status and troubleshooting.

Add read-only tools

The first tool should be to read a file rather than execute a shell.

Pin the allowed directory to the test repository:

1

C:\sandbox\antigravity-demo

Tool parameters need to be path normalized.

Deny absolute paths, .., symbolic link escapes, and hidden network shares.

Set a byte limit on the returned content to avoid stuffing the entire repository into the context.

How to accept the tool call cycle

Each call is logged:

Tool name proposed by Agent.
Original parameters.
Parameter verification results.
Tool exit code.
Truncated output.
Agent’s final conclusion.

Tool executors should not extend permissions on their own based on natural language.

When the Agent requests to read a file, it cannot allow writing by the way.

Do not rely on chat text splicing for status continuation

If the API returns a resumable interaction identifier, the official status mechanism will be used first.

Manually sending all historical messages repeatedly will increase costs and may also cause tool status to be lost.

Before continuing, confirm whether the previous run completed, waited for the tool, or failed.

Do not continue the failure status directly as a success context.

Write operations adopt two-phase submission

The first stage only generates diff.

The second phase is applied after approval by a human or policy engine.

1
2


git diff --check
git diff --stat

Run a minimal set of tests after applying.

When the test fails, keep the working tree and logs, and do not let the Agent automatically clean up the evidence.

Add explicit allow list to command tools

You can first allow:

1
2
3
4


git status --short
git diff --check
npm test -- --runInBand
python -m pytest tests/unit

Deny command splicing, redirection, download execution, and privilege escalation.

Don’t just match by the beginning of the command.

Parameters also need to be verified.

Three boundaries for cost control

Set the maximum number of Agent steps.

Set the maximum output limit for a single tool.

Set time and budget limits for the entire interaction.

After reaching the limit, return to “unfinished” and existing evidence, don’t pretend to be complete.

Common failed positioning

401 Check the key and project first.

403 Check whether the API is open, account qualifications and region.

429 distinguishes between per-minute quotas, daily quotas and concurrency limits.

When a tool calls the same parameters repeatedly, it usually means that the returned results are not structured enough.

The final answer is inconsistent with diff and should be based on the real working tree.

A reliable test task

Prepare a unit test that fails on purpose.

The Agent is asked to find out the cause, but is prohibited from writing files in the first round.

Confirm that it reads the relevant source files and test output.

The second round allows for patch generation.

Apply and run tests after manual review of patches.

Finally, open a new interaction and let another inspection process review the diff.

This exposes permissions and status issues more than letting the Agent modify real projects.

Check before going online

Preview changes are locked to explicit SDK versions.
Keys do not enter repositories and logs.
File tools are restricted to the sandbox root directory.
Command parameters are parsed instead of string prefix matched.
Writes must be approved by diff.
There are limits on steps, time, output and costs.
Preserve evidence of failure status.

The focus of Antigravity Agent is not “the ability to automatically write code”, but whether it can complete code tasks within observable, stoppable, and rollback boundaries.

Agent API official entrance

Design the tool return value to be stable JSON

Tools should not return an entire block of terminal text with indistinguishable status. The file reading result contains at least path, encoding, truncated and content; the command result contains at least exit_code, stdout, stderr and duration_ms. Only the Agent can distinguish between “command failure” and “command success but no output”.

1
2
3
4
5
6
7
8


{
  "tool": "read_file",
  "ok": true,
  "path": "src/app.py",
  "encoding": "utf-8",
  "truncated": false,
  "content": "print('hello')"
}

The results of the command executor can use the following shapes:

1
2
3
4
5
6
7
8


{
  "tool": "run_test",
  "ok": false,
  "exit_code": 1,
  "stdout": "3 passed, 1 failed",
  "stderr": "",
  "duration_ms": 1842
}

ok` is generated by the executor based on the exit code and cannot be filled in by the model itself. When the output is truncated, it also returns the truncation position and allows the Agent to request a smaller range of logs.

Processing after streaming response interruption

Network interruption does not mean that the task is not executed. Query the interaction status before retrying; if the server has accepted the tool results, repeated submission may cause the write operation to be executed twice.

Add idempotent keys for each writing tool. The key consists of interaction ID, tool call ID and target resource, and the executor returns the first result when it finds the same key.

1

idempotency_key = interaction_id + tool_call_id + target

If the official SDK does not expose a status query interface, leave the write operation in the human confirmation stage and do not automatically retry in an uncertain state.

Preview version upgrade record

Each time the SDK is upgraded, the lock file diff, request field changes, response field changes, and a successful recording are saved. First replay on the fixed test task, and then open the real warehouse.

In particular, check whether the tool call parameters have been renamed, whether the status enumeration has been increased, and whether the old interaction can be continued by the new SDK. When the task cannot be continued, let the old task end naturally and do not switch versions during operation.

A fault injection test

Have the reading tool return a timeout to confirm that the agent does not interpret the timeout as a non-existence of the file. Have the test command return an exit code of 1 and an empty stderr to confirm that it still fails. Let the writing tool return “Executed but response lost” to confirm that the idempotent mechanism can prevent the second write.

Finally revoke the test key and rerun the same task. The system should stop during the authentication phase and not request further file permissions.

Create local audit records for Interaction

Audit records do not save the complete source code and prompts, only the metadata required for positioning operations. The recommended structure is as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
  "interaction_id": "int_example",
  "started_at": "2026-07-27T03:00:00Z",
  "model": "replace-with-current-model",
  "repository": "demo-api",
  "base_commit": "8c18d4a",
  "tool_policy": "readonly-v2",
  "tool_calls": 7,
  "write_approved": false,
  "result": "needs_review"
}

repository` uses internal aliases to avoid writing client names into centralized logs. Source code snippets are only saved in task attachments with stricter permissions, and independent expiration times are set.

Parameters still need to be re-verified after manual approval

There may be a time difference between the parameters displayed on the approval interface and the parameters received by the executor. Canonical paths, command argvs, and content hashes are recalculated before execution; any changes invalidate the original approval.

1

approval = hash(tool_name + normalized_arguments + target_revision)

The Agent should regenerate the diff when the target branch changes while waiting for approval. Don’t silently apply old patches to new versions of code.

Leave a continuable state when exiting

Outputs files that have been read, hypotheses that have not yet been verified, the last successful tool invocation, and the work-tree status when budget is reached, timeout, or manual abort.

The next run starts from these facts and does not require rescanning the entire warehouse. If the working tree contains uncommitted modifications, it is up to humans to decide whether to continue, save the patch, or discard it, and the Agent will not clean it up by itself.