Agents.one Directory & Marketplace

Universal template (copy → paste → edit)

# agent.py (Python 3.11, single file, no external deps) import sys, os, json, traceback from datetime import datetime # ── Where to put credentials: # Dashboard → Agent → <your agent> → Credentials → Add "AGENT_OPENAI_KEY" (for example) # Your code reads them from os.environ or the "secrets" dict below. def now(): return datetime.now().strftime('%H:%M:%S') GREEN, RED, RESET = "\033[92m", "\033[91m", "\033[0m" def log(msg, col=GREEN): print(f"{col}[{now()}] {msg}{RESET}", flush=True) def parse_input(raw: str): raw = (raw or "").strip() if not raw: return {"text": "", "json": None} try: if raw[:1] in "{[": return {"text": raw, "json": json.loads(raw)} except Exception: pass return {"text": raw, "json": None} def run_task(user_input: str, secrets: dict): data = parse_input(user_input) # Example: reading a dashboard secret openai_key = secrets.get("AGENT_OPENAI_KEY") or os.environ.get("AGENT_OPENAI_KEY") # Use: if openai_key: call your API. Never print secret values. result = { "received": data["text"], "parsed_json": data["json"], "available_secrets": sorted([k for k in (secrets or {}).keys() if k.startswith("AGENT_")]), } print(json.dumps(result, indent=2), flush=True) def main(): log("Agent started. Waiting for input…") try: user_input = sys.stdin.readline().rstrip("\n") secrets = {k:v for k,v in os.environ.items() if k.startswith('AGENT_')} if user_input.lower() == 'exit': log('Exit command received. Stopping agent.'); return run_task(user_input, secrets) # No need to print "Done." — the Playground shows an idle spinner automatically. except Exception as e: log(f"[ERROR] {e}", RED); traceback.print_exc() if __name__ == '__main__': main()

Advanced (optional): self‑describe the input field. Add this at module level, and we’ll call your agent with PLAYGROUND_DESCRIBE=1 to fetch UI hints.


META = {
  "schema": 1,
  "playground": { "input": { "type": "text", "placeholder": "Type a command" } }
}

def _describe_if_requested():
    import os, sys, json
    if os.environ.get("PLAYGROUND_DESCRIBE") == "1" or (len(sys.argv) > 1 and sys.argv[1] == "--describe"):
        print(json.dumps(META)); sys.exit(0)

Tip: Keep it simple: use the Python standard library and HTTPS APIs. Dashboard‑managed secrets appear as AGENT_* env‑vars. The Playground streams whatever you print with flush=True, shows a server‑driven Loading… spinner during work and Waiting for next input… after.

Ready‑made examples

1. Weather agent (OpenWeatherMap)

Type a city name → returns live weather.


import os, json, urllib.request, urllib.parse
def run_task(city, secrets):
    key = secrets.get('AGENT_OWM_KEY') or os.environ.get('AGENT_OWM_KEY')
    if not key: raise RuntimeError('Missing AGENT_OWM_KEY (add it in Credentials)')
    q = urllib.parse.quote(city.strip())
    url = f"https://api.openweathermap.org/data/2.5/weather?q={q}&units=metric&appid={key}"
    with urllib.request.urlopen(url, timeout=8) as r:
        data = json.loads(r.read().decode('utf-8', 'ignore'))
    out = {'city': data.get('name'),
           'temp': (data.get('main') or {}).get('temp'),
           'sky': ((data.get('weather') or [{}])[0]).get('description')}
    print(json.dumps(out, indent=2))

2. Crypto quote (CoinGecko)

Type e.g. bitcoin → price in USD.


import json, urllib.request
def run_task(symbol,_):
    s = symbol.strip().lower()
    url = f"https://api.coingecko.com/api/v3/simple/price?ids={s}&vs_currencies=usd"
    with urllib.request.urlopen(url, timeout=6) as r:
        data = json.loads(r.read().decode('utf-8', 'ignore'))
    if s not in data: raise ValueError('Unknown coin id')
    print(json.dumps({'coin': s, 'usd': data[s]['usd']}, indent=2))

3. Text‑summariser (OpenAI via HTTP)

Paste text → GPT summary (no SDK required).


import os, json, urllib.request
def run_task(text, secrets):
    key = secrets.get('AGENT_OPENAI_KEY') or os.environ.get('AGENT_OPENAI_KEY')
    if not key: raise RuntimeError('Missing AGENT_OPENAI_KEY (add it in Credentials)')
    body = {
      "model": "gpt-4o-mini",
      "messages": [
        {"role": "system", "content": "Summarise in 3 concise sentences."},
        {"role": "user", "content": text}
      ]
    }
    req = urllib.request.Request("https://api.openai.com/v1/chat/completions",
                                 data=json.dumps(body).encode("utf-8"),
                                 headers={"Authorization": f"Bearer {key}",
                                          "Content-Type": "application/json"})
    with urllib.request.urlopen(req, timeout=20) as r:
        data = json.loads(r.read().decode("utf-8", "ignore"))
    summary = (data.get("choices") or [{}])[0].get("message", {}).get("content", "").strip()
    print(json.dumps({"summary": summary}, indent=2))

Environment variables available to you

Variable	Description
AGENT_* (custom)	Dashboard‑managed secrets. Access in code via `os.environ['AGENT_X']` or `secrets.get('AGENT_X')`. The Playground redacts values if they’re accidentally printed.
PLAYGROUND_RUN_ID	Unique ID for a run (visible in Logs once enabled).
PLAYGROUND_USER_IP	Visitor IP (proxied) if your listing enables it (v2).
PLAYGROUND_DESCRIBE	Set to `"1"` when we call your agent to fetch UI hints (`META.playground.input`), so you can exit early with JSON.

Milestones

v1 — Live

Now

Directory — public listing of agents
Build uploads — agent makers & agency managers upload .zip (.py‑only, includes agent.py); admin approves before public use.
Builds index — system‑wide builds list with filters (admins see all; makers/agency see only their own).
Playground — live terminal, SSE output, server‑driven spinners
Credentials — set AGENT_* in Dashboard; auto‑injected as env vars

v2 — Next

WIP

Logs — view recent runs per agent (secrets redacted)
Enable / Disable playground per agent

v3 — Planned

Roadmap

Paid gates & Stripe billing
Embeddable widgets & rate limiting

v4 — Exploratory

Future

GPU sandboxes
Team seats & audit

Need help shaping your agent.py? We can assist with integration & best‑practices at cost.

Frequently Asked Questions

Who can upload builds?

Agent makers and agency managers can upload a .zip containing only .py files (must include agent.py). An admin reviews and must approve the build before it becomes available in the public Playground.

Where do I add API keys or credentials?

In v2, go to Agent → your agent → Credentials and add items named like AGENT_OPENAI_KEY or AGENT_OWM_KEY. They are injected into your agent as environment variables at runtime. The platform also redacts AGENT_* values from streamed logs automatically.

How do I read those credentials in my agent.py?

Use os.environ['AGENT_X'] or the provided secrets dict. Example: key = secrets.get('AGENT_OPENAI_KEY') or os.environ.get('AGENT_OPENAI_KEY'). Never print secret values—log only the names if needed.

What does the Playground run exactly?

A short‑lived Python 3.11 process executes your agent.py. Packages must contain only .py files; no virtual environments or binary dependencies are accepted in v1. Output is streamed from stdout as you print with flush=True.

Which inputs are supported?

Plain text, URLs, and JSON strings. The Playground validates URLs (requires http/https and public hosts) and JSON syntax before running. Non‑printable control characters and oversized inputs are rejected.

Can my agent call external APIs?

Yes, via the Python stdlib (e.g., urllib.request) or your code. Outbound network access is governed per approved version; admins can enable or disable it during approval (allow_net).

Why do I see “Loading …” and “Waiting for next input …” spinners?

Spinners are server‑driven over SSE. We show Loading … while your agent runs (contextual to the input type), and a persistent Waiting for next input … when it completes. The connection stays open with heartbeats so users can immediately run another input.

Where can I view run logs?

Open Agent → your agent → Logs (v2) for recent runs with stdout/stderr (secrets masked) and metadata like run IDs.

Does the Playground keep state between runs?

Treat each run as stateless. If you need persistence, use your own backend.

Is there a recommended file size or dependency strategy?

Keep agent.py small for fast cold starts. In v1, ship only Python files. (Support for dependencies may expand in later versions.)

Can I restrict access or disable my Playground?

Planned in v2: Disable and Invite‑only modes. Until then, unpublish the listing to pause access.

Can I charge for access?

Billing and pay‑gated playgrounds are planned for v3.

Is GPU available?

Not currently. CPU is standard.

Need help preparing agent.py?

We offer paid implementation support to adapt your agent to this template (credentials, streaming, error handling). Contact us.

Agents.one Playground

Why a playground?