API Spreadsheets Logo

Creating & Running Spreadsheet Agents

API Spreadsheets Team ·

Creating & Running Spreadsheet Agents

What are Spreadsheet Agents?

Spreadsheet Agents let you combine multiple spreadsheets, generate analyses/visualizations, and export results (HTML, XLSX, etc.). Unlike static exports, Agents use LIVE Spreadsheet API URLs under the hood—so when your Google Sheet values change, linked visualizations can reflect the new data.

What you’ll build

Prerequisites

Where to find your keys

Dashboard → API Keys (Account Access Key & Secret Key)
Dashboard → API Keys (Account Access Key & Secret Key)

Install the client

pip install apispreadsheets

End-to-end Python (two files → agent → run → poll → outputs)

Use environment variables for credentials; then run the script below. You can download it directly from the button on this page or copy the code shown here.

import os, time
from typing import List, Dict, Any
from apispreadsheets import APISpreadsheets

account_access_key = os.getenv("ACCOUNT_ACCESS_KEY")
account_secret_key = os.getenv("ACCOUNT_SECRET_KEY")
if not (account_access_key and account_secret_key):
    raise SystemExit("Set ACCOUNT_ACCESS_KEY and ACCOUNT_SECRET_KEY")

client = APISpreadsheets(access_key=account_access_key, secret_key=account_secret_key)

# 1) Import two spreadsheets
files_to_import = [os.getenv("AGENT_FILE_1", "characters.xlsx"),
                   os.getenv("AGENT_FILE_2", "characters_v2.xlsx")]
import_results = client.import_files(files=files_to_import)
file_ids: List[str] = [r["results"][0]["createResult"]["fileID"] for r in import_results["results"]]

# 2) Build agent (live visual)
build = client.build_agent(
  agentName="Character Profit Analysis Agent",
  agentDescription="Analyzes profit across characters from multiple spreadsheets.",
  selectedFiles=file_ids,
  fileDescriptions={
    file_ids[0]: "Characters + profit column.",
    file_ids[1]: "Names of characters and profit.",
  },
  selectedOutputFormats=[".html"],  # also supports .xlsx
  agentInstructions="Make a live visualization of all the information in the files."
)
agent_hash = build["agent_hash"]; agent_ak = build["access_key"]; agent_sk = build["secret_key"]

# 3) Run agent
run = client.run_agent(
  agent_hash=agent_hash,
  temperature=0.1, top_p=0.9,
  access_key=agent_ak, secret_key=agent_sk,
  file_ids=file_ids,
  file_descriptions={
    file_ids[0]: "Characters + profit column.",
    file_ids[1]: "Names of characters and profit."
  }
)
job_id = run["job_id"]

# 4) Poll for completion
while True:
  status = client.agent_job_status(job_hash=job_id, access_key=agent_ak, secret_key=agent_sk)
  if status["status"] == "completed":
    print("Completed:", status)
    break
  if status["status"] in ("running","starting"):
    print("Waiting…"); time.sleep(5)
  else:
    print("Failed:", status); break

Viewing results

When the job is completed, the payload includes download_url entries. HTML outputs can be live, meaning they read from live spreadsheet API URLs on load. Example (from a previous run):

https://woyera-production-files.s3.amazonaws.com/agent-outputs/DdboCJBCq9CTRhv1_live_character_data_visualization.html?...

Live outputs vs static

Tips