Metadata-Version: 2.5
Name: game-plugin-oneshot
Version: 0.24.0
Summary: GAME SDK plugin for OneShot real-world AI agent tools — 54 tools
Project-URL: Homepage, https://oneshotagent.com
Project-URL: Repository, https://github.com/oneShotAgentSDK/game-plugin-oneshot
Project-URL: Documentation, https://docs.oneshotagent.com/sdk/overview
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: game-sdk>=0.1.5
Requires-Dist: oneshot-python>=0.49.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install game-plugin-oneshot
```

## Start

```python
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:

```python
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](https://docs.oneshotagent.com/sdk/remote-mcp).

## What it does

| Area | Tools |
|------|-------|
| [Talk](https://docs.oneshotagent.com/api-reference/email/send) | `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](https://docs.oneshotagent.com/api-reference/email/domains) | `oneshot_list_domains` `oneshot_pause_domain` `oneshot_resume_domain` |
| [Find people](https://docs.oneshotagent.com/api-reference/research/person-find) | `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](https://docs.oneshotagent.com/api-reference/research) | `oneshot_research` `oneshot_solve` `oneshot_predict` |
| [Web and buying](https://docs.oneshotagent.com/api-reference/web-search) | `oneshot_web_search` `oneshot_web_read` `oneshot_product_find` `oneshot_commerce_buy` |
| [Physical mail](https://docs.oneshotagent.com/api-reference/physical-mail/overview) | `oneshot_physical_mail_upload` `oneshot_physical_mail_preview` `oneshot_physical_mail_approve` `oneshot_physical_mail_send` |
| [Connected systems](https://docs.oneshotagent.com/api-reference/connections/overview) | `oneshot_connections_list`, then `oneshot_ledger_*` `oneshot_crm_*` `oneshot_tax_*` `oneshot_shipping_*` `oneshot_procurement_*` |
| [Browser](https://docs.oneshotagent.com/api-reference/browser/create) | `oneshot_browser` `oneshot_browser_create_profile` `oneshot_browser_list_profiles` `oneshot_browser_delete_profile` |
| [LinkedIn](https://docs.oneshotagent.com/api-reference/linkedin/overview) | `oneshot_linkedin_connect` `oneshot_linkedin_accounts` `oneshot_linkedin_invite` `oneshot_linkedin_withdraw_invitation` `oneshot_linkedin_message` `oneshot_linkedin_reply` and more |
| [Build](https://docs.oneshotagent.com/api-reference/build/create) | `oneshot_build` `oneshot_update_build` |
| [Money](https://docs.oneshotagent.com/api-reference/budgets/overview) | `oneshot_get_balance` `oneshot_budget_status` |
| [Data](https://docs.oneshotagent.com/api-reference/lookup/company-filings) | 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](https://pypi.org/project/oneshot-python/). [Prices](https://docs.oneshotagent.com/pricing).

## 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.

```python
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.

## Links

- [Documentation](https://docs.oneshotagent.com/sdk/virtuals)
- [oneshot-python](https://pypi.org/project/oneshot-python/): the core client
- [langchain-oneshot](https://pypi.org/project/langchain-oneshot/): the same tools for LangChain
- [TypeScript SDK](https://www.npmjs.com/package/@oneshot-agent/sdk)
- [MCP Server](https://www.npmjs.com/package/@oneshot-agent/mcp-server)
- [GitHub](https://github.com/oneshot-agent/sdk)

## 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
