game-plugin-oneshot

Your Virtuals agent can plan. This lets it act: send email, make calls, research, buy, build sites. It pays per action from your wallet, and spends nothing you did not allow.

Install

pip install game-plugin-oneshot

Start

import os
from game_sdk.game.agent import Agent
from game_plugin_oneshot import OneShotPlugin

plugin = OneShotPlugin(private_key=os.environ["WALLET_PRIVATE_KEY"])

agent = Agent(api_key=os.environ["GAME_API_KEY"], name="my-agent",
              agent_description="An agent that can interact with the real world")
agent.add_worker(plugin.get_worker())
agent.run()

Fund the wallet with USDC on Base first. Paid tools quote, pay and return the result.

Access-token sessions

For a hosted agent that must not hold the key:

plugin = OneShotPlugin(access_token=os.environ["ONESHOT_ACCESS_TOKEN"])
# Inside an event loop, use instead:
# plugin = await OneShotPlugin.acreate(access_token=os.environ["ONESHOT_ACCESS_TOKEN"])

A token spends prepaid credits only. It never signs a payment.
It reads budgets but cannot change them, and cannot mint or revoke tokens.
Create it, set budgets and top up (OneShotClient.top_up_credits(amount)) from a wallet session. Hosted setup.

What it does

Area	Tools
Talk	`oneshot_email` `oneshot_sms` `oneshot_voice` `oneshot_inbox_list` `oneshot_inbox_get` `oneshot_sms_inbox_list` `oneshot_sms_inbox_get` `oneshot_notifications` `oneshot_mark_notification_read`
Send from your domains	`oneshot_list_domains` `oneshot_pause_domain` `oneshot_resume_domain`
Find people	`oneshot_person_find` `oneshot_person_profile` `oneshot_person_email` `oneshot_person_email_status` `oneshot_person_dossier` `oneshot_person_social_accounts` `oneshot_person_articles` `oneshot_person_posts` `oneshot_person_interests` `oneshot_person_followers`
Think	`oneshot_research` `oneshot_solve` `oneshot_predict`
Web and buying	`oneshot_web_search` `oneshot_web_read` `oneshot_product_find` `oneshot_commerce_buy`
Physical mail	`oneshot_physical_mail_upload` `oneshot_physical_mail_preview` `oneshot_physical_mail_approve` `oneshot_physical_mail_send`
Connected systems	`oneshot_connections_list`, then `oneshot_ledger_` `oneshot_crm_` `oneshot_tax_` `oneshot_shipping_` `oneshot_procurement_*`
Browser	`oneshot_browser` `oneshot_browser_create_profile` `oneshot_browser_list_profiles` `oneshot_browser_delete_profile`
LinkedIn	`oneshot_linkedin_connect` `oneshot_linkedin_accounts` `oneshot_linkedin_invite` `oneshot_linkedin_withdraw_invitation` `oneshot_linkedin_message` `oneshot_linkedin_reply` and more
Build	`oneshot_build` `oneshot_update_build`
Money	`oneshot_get_balance` `oneshot_budget_status`
Data	one `oneshot_<name>` per lookup in the `oneshot-python` manifest; a new lookup appears without a plugin release

Payment

Paid tools settle in USDC on Base, or spend credits through an access token. The money rules live in oneshot-python. Prices.

Complex arguments

GAME arguments are scalars. Objects go in as JSON strings (oneshot_commerce_buy, oneshot_build, oneshot_update_build, the blocks of oneshot_solve and oneshot_predict); lists go in comma-separated. The agent writes them itself.

import json

shipping_address = json.dumps({"first_name": "John", "last_name": "Doe", "street": "123 Main St",
                               "city": "Austin", "state": "TX", "zip_code": "78701", "phone": "+15551234567"})

Tool notes

Phone lookup is off by default. include_phone="true" on oneshot_person_find is charged for each person you ask for, found or not; a failed job is refunded.
Physical mail. U.S. letters and postcards. Check the proof and the price with oneshot_physical_mail_preview, then approve with oneshot_physical_mail_approve. Nothing approves it for you. Keep the idempotency key before oneshot_physical_mail_send.

Configuration

Parameter	Default	Meaning
`private_key`	required, unless `access_token`	Hex-encoded wallet key
`access_token`	`None`	Credits-only session; not with `private_key`, `budgets` or `alert_email`
`address`	`None`	The token's wallet; looked up when omitted
`base_url`	`None`	Override the server URL
`budgets`	`None`	Server-enforced cap, e.g. `{"daily": 50, "per_transaction": 5}`. The agent reads it with `oneshot_budget_status`; it cannot change it
`alert_email`	`None`	Where budget alerts go

LinkedIn recovery

No active account, or one that is connection_deleted or revoked: ask the human to run oneshot_linkedin_connect again. Reconnect (for reconnect_required) and revoke are handled by the owning application. They are deliberately not agent tools. Never open a new connection on your own after an auth failure or a timeout.

Requirements

Python 3.10 or newer. pip installs game-sdk and oneshot-python with it.

Discover tools

The toolkit exposes oneshot_discover_tools for free public tool search. Optional query, category and cursor arguments mirror OneShotClient.discover_tools. With no arguments it lists category counts; searches return public MCP names, purposes and required inputs, filtered by the caller's grants.

License

MIT

Metadata

Release files for game-plugin-oneshot 0.24.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for game-plugin-oneshot 0.24.0
File	Size	Uploaded	Provenance
game_plugin_oneshot-0.24.0.tar.gz	111.0 kB	Oct 23, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for game-plugin-oneshot 0.24.0
File	Interpreter	ABI	Platform	Reset
game_plugin_oneshot-0.24.0-py3-none-any.whl 22.9 kB Oct 23, 2026 Without provenance	Python 3	none	any	Details

Total release size: 133.8 kB

Release files / game_plugin_oneshot-0.24.0.tar.gz

Download URL	game_plugin_oneshot-0.24.0.tar.gz
Size	111.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`31bc01bb6481b21c5046b43202bfe9380251bc6f52ddef64f19169b5331a604e`
BLAKE2b-256 checksum How to use checksums	`3e90641658883d66ea25ce8034a49378f0d9824f86e56404ac75d22b96be1c78`
Upload date	Oct 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.15`

Release files / game_plugin_oneshot-0.24.0-py3-none-any.whl

Download URL	game_plugin_oneshot-0.24.0-py3-none-any.whl
Size	22.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`9a0fbdd7da978febae5223c74d9649e7de57d3680c6e09255f6518f95a4cfc1c`
BLAKE2b-256 checksum How to use checksums	`3dfb9edd7b03ddbf3df9bdc3e5fd04892479f727db4105d25328b09f182d4c25`
Upload date	Oct 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.15`

Security for game-plugin-oneshot 0.24.0

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.