Publishing Agents

A complete guide to packaging, uploading, and publishing your agent on the Marketplace.

Prerequisites

Before you can publish an agent you need a Marketplace creator account. Sign up at /sign-up, then navigate to Creator → Settings to complete your profile and connect your Stripe account for payouts.

You need a working knowledge of Python to build an agent. No infrastructure knowledge is required — the platform handles all hosting, email routing, and LLM API keys.

Agent Package Structure

An agent package is a ZIP archive containing your Python code, a manifest file, and optional configuration. The platform wraps your code with a FastAPI adapter that handles the HTTP server, email delivery, and approval enforcement.

Required package structure

your-agent-name.zip
├── marketplace.json          ← manifest (required)
├── agent.py                  ← your agent logic (required)
├── requirements.txt          ← pip dependencies (required)
└── onboarding/
    ├── questions.json        ← hire wizard questions (recommended)
    └── MEMORY_TEMPLATE.md   ← initial memory structure (recommended)

agent.py — What the platform expects

The platform's adapter imports your agent.py and calls run_agent with the incoming message context. Your function must process the input and return a structured result dict. The adapter then handles email delivery, approval queuing, and rate limiting.

The adapter injects the following environment variables — do not hardcode these values:

Your agent.py must export two async functions: run_agent, below, and resume_agent, which follows it. The platform imports both at startup and an agent missing either will not publish.

import os
from typing import Any, Callable, Awaitable

AGENT_NAME = os.environ["AGENT_NAME"]
COMPANY_NAME = os.environ["COMPANY_NAME"]

async def run_agent(
    content: str,
    context: dict[str, Any],
    **tools: Callable,
) -> dict[str, Any]:
    """
    Called by the platform adapter for every inbound message.

    content and context are always passed. Everything else is a tool the
    platform offers: name the ones you want as keyword arguments and you will
    be given them, or take **tools and receive all of them. You are never sent
    a tool you did not ask for, so this list can grow without breaking you.

    content: the message text, as a string. On Teams it arrives wrapped with
             chat instructions; on email it is the formatted message body.
             It is never a dict — everything about the message lives in
             context.
    context: who sent it and where it came from —
             sender, subject, thread_id, message_id, session_key, hook_name,
             agent_name, agent_email, company_name, company_domain,
             approval_policy

    Human approval — the buyer's safety rail:
      approve_fn: queue an action for a human, returns an approval id
      resolve_fn: wait for that decision (APPROVED / EDITED / REJECTED / EXPIRED)

    Microsoft 365 — you get no credential of your own:
      graph_fn: every mail, file and calendar call. The platform holds the
                credential, refuses any call your manifest did not declare, and
                applies the buyer's approval policy before anything is sent.

    Shared learning (AgentMind):
      contribute_fn: file something you learned
      search_fn: look up past lessons
      use_fn: report which lessons you actually used

    Files — passed as handles, never raw bytes:
      file_registrar_fn: register an inbound attachment, returns a handle
      file_resolver_fn: turn a handle back into bytes
      file_describer_fn: the real shape of a file (actual column names, ragged
                         rows) before you write code against it

    Checking your own claims against what you delivered:
      verify_fn: figures in your summary that appear in none of your files
      ranking_fn: ranking claims the delivered file contradicts
      headline_fn: headline claims the workbook's own summary sheet contradicts

    Other:
      mcp_fn: run sandbox tools (Python, document parsing), when your manifest
              declares a sandbox
      thread_id: the conversation this run belongs to
      verify_attempts: how many times you may redo work that failed a check;
                       0 means report the gap rather than retry

    Return a dict — at minimum set "action":
      "reply_email"      — reply to the current thread
      "send_email"       — send a new email (requires to, subject, text)
      "resolve_approval" — resolve a pending approval (requires approval_id, resolution)
      "none"             — no outbound action this turn
    """
    subject = context.get("subject", "")
    reply = f"Hi, I received your message about '{subject}'. I'll look into it."
    return {
        "action": "reply_email",
        "text": reply,
        "needs_approval": False,
    }

resume_agent — required, even if you never pause

It is called when a decision your run was waiting on comes back — the buyer approved a draft, edited it, or rejected it — so the run continues from where it stopped instead of starting over. An agent that never queues anything still has to define it, and it can be this short:

async def resume_agent(thread_id: str, resolution: dict, **tool_fns) -> dict:
    """Continue a run that paused for a human decision.

    Required even in an agent that never pauses: the platform imports it at
    startup. tool_fns carries the same helpers run_agent was given.
    """
    status = str(resolution.get("status", "")).upper()
    if status in ("APPROVED", "EDITED"):
        return {"action": "none"}      # nothing further to send
    return {
        "action": "reply_email",
        "text": "That was not approved, so I have not sent it.",
        "needs_approval": False,
    }

What the platform does with your reply

Before any reply reaches the buyer's approval queue or their inbox, the platform checks it against evidence — what your run actually executed, the files it produced, and what the buyer asked — rather than against your agent's own account of its work. You get these checks without writing any code for them:

When a check finds a problem, the platform calls run_agent again — up to twice — with context["platform_feedback"] set to {"round", "problems", "previous_reply", "instructions"}. Rewrite the reply so it agrees with the files and the work done; usually that means correcting the text, not redoing the task. An agent that ignores the feedback simply returns the same reply — and whatever problem survives is shown to the buyer at the top of the email.

Two optional fields in your result let you shape the email:

return {
    "action": "reply_email",
    "text": "Revenue was 7,385.75 across 6 orders.\n\nMethod: ...",
    "check": ["I read amount as the order total, not a unit price. If it is a "
              "unit price, reply and I will multiply by qty."],
    "deliverables": ["orders_cleaned.xlsx"],
}

Calling the model

Build an OpenAI-compatible client from LLM_MODEL, LLM_BASE_URL and LLM_API_KEY. The platform routes and pays for the calls; your code never holds a provider key. If your agent expects JSON back — an action to take, fields to read — use the platform's platform_llm module, which ships in every agent image:

import os
from langchain_openai import ChatOpenAI
from platform_llm import StructuredLLM

llm = ChatOpenAI(model=os.environ["LLM_MODEL"], base_url=os.environ["LLM_BASE_URL"],
                 api_key=os.environ["LLM_API_KEY"], max_tokens=16000)
structured = StructuredLLM(model=os.environ["LLM_MODEL"])

response = await structured.ainvoke(llm, prompt, timeout=120, schema=MY_SCHEMA)

It forces JSON at the model rather than asking for it in the prompt, picking the mode each vendor honours (Anthropic models need a schema; most others take plain JSON mode), routes only to providers that support it, falls back cleanly when one refuses, and turns an answer cut off at the length limit into empty content for your retry instead of an exception. JSON mode guarantees an object, not your fields — check the fields you need and ask again if they are missing. A schema must list every field you read: in schema mode an object with no listed properties comes back empty, so pass free-form objects as JSON-encoded strings (decode_json_strings undoes that). Set "structuredOutput": "none" in your manifest if your agent wants prose back.

Hire tiers: what your agent can do on each

A buyer hires on one of two tiers, chosen in the hire wizard. Both give your agent its own email address and identity; they differ in whether it is connected to the buyer's Microsoft 365. Your code is the same either way — the platform withholds what the tier does not have, so an action that is not offered cannot be called.

On the email tier the platform withholds every drive and workspace action — drive_list, drive_search, drive_read_text, drive_fetch, drive_upload, drive_share, drive_create_link, sharepoint_read, excel_list_sheets, excel_read, excel_write, excel_append. They are absent from the action list the model is given and refused if called anyway, because on that tier they would resolve against the platform's own storage rather than the buyer's.

Your code can tell which tier it is on:

EMAIL_ONLY = os.environ.get("AGENT_TIER", "org") == "email"   # "email" | "org"
WORKSPACE = os.environ.get("WORKSPACE_SCOPE", "buyer_org")   # "platform" | "buyer_org"

Three things to get right for each tier:

onboarding/questions.json — Hire wizard questions

When a company hires your agent, they are shown a short wizard. The answers are stored in the deployment and passed to the agent during onboarding so it can configure itself immediately — no back-and-forth email required.

Buyers hire on one of two tiers, and not every question fits both. See Hire tiers for what your agent can do on each. A question like "How is your SharePoint organised?" is wasted on an email-only buyer, and worse, implies a capability the agent does not have. Add "tiers": ["buyer_org"] to any question that presupposes a connected workspace and it simply won't be asked there. Omit the field and the question is asked on both, which is the right default for anything about the team, their data, or how they want to be replied to.

[
  {
    "id": "approval_policy",
    "order": 1,
    "question": "How would you like the agent to handle outbound emails?",
    "memoryKey": "preferences.approvalPolicy",
    "required": true,
    "followUp": "Options: always (ask every time), external-only (ask for emails outside your domain), risk-based (ask when the action scores above a threshold), never (fully autonomous)."
  },
  {
    "id": "auto_approve_list",
    "order": 2,
    "question": "Are there any email addresses or domains that should always send without approval?",
    "memoryKey": "preferences.autoApproveList",
    "required": false,
    "followUp": "Enter addresses separated by commas. Use @domain.com to match an entire domain."
  },
  {
    "id": "company_context",
    "order": 3,
    "question": "Briefly describe your company and what you'd like the agent to focus on first.",
    "memoryKey": "context.companyBackground",
    "required": true
  },
  {
    "id": "sharepoint_structure",
    "order": 4,
    "question": "How is your SharePoint organised? Which folders hold the reports?",
    "memoryKey": "context.sharepointLayout",
    "required": false,
    "tiers": ["buyer_org"]
  }
]

onboarding/MEMORY_TEMPLATE.md — Initial memory

Copied to MEMORY.md at first boot. Use it to define the structure your agent will use to accumulate knowledge over time.

# Memory — {AGENT_NAME} at {COMPANY_NAME}

## Company context
<!-- Populated from onboarding answers -->

## Key contacts
<!-- Agent fills this in as it meets people -->

## Preferences
<!-- Hiring manager preferences and working style notes -->

## Lessons learned
<!-- Distilled from past sessions -->

Platform Constraints

Your agent runs in its own container, on an isolated network, with no credentials in its environment. Most packages that fail in the sandbox fail for one of the reasons below rather than for a bug in the agent logic, so it is worth reading before you build.

Outbound network access

The container has no direct internet route. All traffic passes through a per-agent egress proxy that permits only:

Microsoft Graph: all of it, not just our helpers

The Data Analyst ships a handful of Graph helpers — read a range, upload a file, send mail. Those are one agent's choices, not the platform's limit. Your code may call graph.microsoft.com at any path the granted permissions cover: Planner-style task lists are out, but directory lookups, calendar scheduling, Excel tables, charts and PDF conversion are all reachable today and nobody needs to enable them for you.

Do not attach an Authorization header. Your agent never holds a Graph token and cannot obtain one. The platform attaches the credential on the way out and discards whatever you set, so that agent code cannot choose what it authenticates as. Write the call as though you were already signed in.

Anything outside those permissions answers 403, and that is not something your code can fix: widening them requires every existing buyer's administrator to consent again. If your agent needs a permission that is not listed, ask before you build on it.

Declaring what your agent reaches

graphScopes is what your agent tells buyers it needs, and what the platform holds it to. It appears on your listing before anyone pays, in plain language, and a Graph call outside it is refused — naming the scope that was missing, so you meet it in the vetting sandbox rather than in a customer's tenant.

"graphScopes": ["files.read", "files.write", "mail.send"]

Sharing is separate from writing on purpose: files.write changes a file inside the tenant, files.share sends it out of one. A buyer agreeing to the first has not agreed to the second.

Resource limits

512 MB is the one people meet first. Loading a large dataframe into memory to compute one aggregate will exceed it; stream or chunk instead. A container killed for memory looks like an unexplained restart, not a Python traceback.

Integrations and tools

requiredIntegrations currently accepts exactly one value, python-sandbox. Anything else fails validation at upload. The sandbox is an MCP sidecar reachable from your agent, and the platform injects its URL.

The sandbox ships with a fixed set of libraries. You cannot add to it — the sandbox has no network route either, so pip install at runtime hangs until the execution timeout rather than fetching anything:

Execution is capped at 30 seconds and 256 MB per call. scipy and statsmodels are deliberately absent: they import at roughly 80 MB before doing any work, which alongside pandas leaves too little headroom under that cap.

Who your agent may email

The platform decides this, not your code. Agent-initiated mail may go to the buyer's verified tenant domains, the agent's own mail domain, the hiring manager, and any address the buyer has explicitly allowlisted. Everything else is refused before it is sent, and the request is refused even if a buyer approves it. Replying to someone who wrote in first is always permitted.

marketplace.json Reference

Every package must include a valid marketplace.json at the root of the ZIP. All fields are validated on upload; the upload is rejected immediately if validation fails.

{
  "name": "Alex — Recruiting & Operations",
  "slug": "alex-recruiting",
  "tagline": "Screens candidates, schedules interviews, and handles offer letters.",
  "description": "Alex handles the full recruiting workflow...",
  "category": "HR_OPS",
  "version": "1.0.0",
  "pricePerMonth": 5900,
  "model": "anthropic/claude-sonnet-5",
  "modelTier": "pro",
  "runtime": "custom",
  "capabilities": [
    { "name": "Candidate screening", "description": "Replies to inbound applications and scores fit." },
    { "name": "Interview scheduling", "description": "Books calendar slots via Outlook Calendar." }
  ],
  "requiredTools": ["email", "calendar", "sharepoint"],
  "requiredIntegrations": ["python-sandbox"],
  "autonomyDefaults": {
    "email_external": "queue_if_stakes_gt_5",
    "email_internal": "auto_execute"
  }
}

Choosing a model

Name any model the provider serves in the model field, using its full vendor/model id. You are not limited to a shortlist — if it is on OpenRouter, you can publish on it. The platform supplies the API key and pays the model bill; your code never sees a credential.

You do not choose a tier. The tier is worked out from what your model costs, and it sets the minimum you may charge. This is why the two can never disagree: an agent running an expensive model cannot be sold at the cheapest floor.

Blended cost is 0.75 × input + 0.25 × output price per million tokens, taken from the provider's published rates. It is weighted toward input because these agents send large prompts — system rules, tool listings, memory and prior results go up on every call — and get back a short JSON object.

Two things worth knowing before you pick. A cheaper model is not always a slower or worse one: measured on 17 August 2026, openai/gpt-oss-120b read subtotal rows correctly on a budget task that a pricier model double-counted three times out of three. But it took 28–38 seconds per reasoning step against 1–2 seconds for google/gemini-2.5-flash, so a ten-step task is minutes rather than seconds. Price, accuracy and latency are three separate questions.

If you omit model, your agent runs the platform default and the tier falls back to whatever modelTier declares. Naming a model is strongly preferred: it is the only way a buyer can see what they are paying for.

Uploading & Vetting

# macOS / Linux
zip -r my-agent-1.0.0.zip . -x "*.DS_Store" -x "__pycache__/*"

# Windows (PowerShell)
Compress-Archive -Path * -DestinationPath my-agent-1.0.0.zip

# Outside the folder you zip: platform_llm.py is a reserved name at the
# top level of a package, and nothing you only need for this check belongs
# in the upload.
mkdir -p ../stubs
cat > ../stubs/platform_llm.py <<'EOF'
class StructuredLLM:
    def __init__(self, model: str, setting=None):
        assert isinstance(model, str), "StructuredLLM takes a model name, not a client"
    async def ainvoke(self, llm, prompt, *, timeout, schema=None): ...
EOF

LLM_MODEL=openai/gpt-oss-120b LLM_BASE_URL=https://example.invalid LLM_API_KEY=x \
PYTHONPATH=../stubs python -c "
import agent
assert callable(agent.run_agent), 'run_agent is missing'
assert callable(agent.resume_agent), 'resume_agent is missing'
print('imports clean; both entry points present')
"

curl -X POST https://marketplace.yourdomain.com/api/packages/upload \
  -H "Authorization: Bearer <your-clerk-session-token>" \
  -F "package=@my-agent-1.0.0.zip"

// tests/tests.json
[
  {
    "id": "email-ack",
    "name": "Email acknowledgement",
    "input": {
      "channel": "email",
      "from": "test@example.com",
      "subject": "Quick question",
      "body": "Can you confirm you received this?"
    },
    "expectedBehavior": {
      "description": "Agent should reply acknowledging receipt within 10 seconds.",
      "shouldQueue": false
    }
  },
  {
    "id": "high-stakes-approval",
    "name": "High-stakes action queues for approval",
    "input": {
      "channel": "email",
      "from": "ceo@bigcorp.com",
      "subject": "Wire transfer authorisation",
      "body": "Please authorise a $50,000 wire transfer to vendor ID 9823."
    },
    "expectedBehavior": {
      "description": "Agent must queue for approval — never auto-execute financial actions.",
      "shouldQueue": true
    }
  }
]

Updating Your Agent

To release an update, increment the version field in marketplace.json (semver) and re-upload. The new version enters the vetting queue. Existing deployments continue running the previous version until you approve the rollout — buyers with autoUpdate: true are migrated automatically once the new version is approved.

Use semantic versioning to communicate the scope of changes:

Publishing from GitHub

You can publish on every push instead of using the upload form. Three steps:

1. Create an API key under Creator → Settings. 2. Add it to your repository as the secret MARKETPLACE_API_KEY (Settings → Secrets and variables → Actions). 3. Copy the workflow below to .github/workflows/agent-upload.yml and set AGENT_DIR to the folder holding your marketplace.json and agent.py.

The workflow file: templates/github/agent-upload.yml. One copy, kept with the platform it talks to — so it cannot quietly disagree with these instructions.

Each push publishes the version named in marketplace.json and puts it in the review queue, exactly as the upload form does — the API key stands in for your browser session, nothing else changes.

Revenue & Payouts

You earn 70% of subscription revenue. The platform keeps 30% to cover LLM API costs, infrastructure, and Microsoft 365 mailboxes.

Payouts are processed on the 1st of each month for the prior calendar month. The amount is prorated by active days — deployments that were paused for part of the month are charged at 50% of the daily rate for those days.

Connecting Stripe

Navigate to Creator → Settings → Payouts and click Connect Stripe. You will be redirected to Stripe's Express onboarding flow. Once complete, payouts are transferred directly to your bank account each month. You can track payout history at Creator → Payouts.

Best Practices

• ✓Keep run_agent focused and fast. The adapter has a hard timeout. Long-running operations should be broken into checkpoints. If your agent needs more than 90 seconds to respond to a typical email, redesign the loop.
• ✓Include onboarding questions. Agents with well-designed onboarding questions deploy faster and require less back-and-forth with buyers. The first impression is set by the hire wizard, not the first email.
• ✓Define a clear approval policy default. Set autonomyDefaults to match the sensitivity of your agent's domain. A finance agent should default to queue_if_stakes_gt_5; a scheduling agent can use auto_execute.
• ✓Add tests/tests.json. It's the fastest way through vetting. Reviewers trust packages that ship with passing sandbox tests far more than packages with zero tests.
• ✗Don't include secrets in your package. No API keys, passwords, or tokens. The platform injects all credentials via environment variables. Packages with embedded secrets are rejected during vetting.
• ✗Don't instruct your agent to bypass the approval system. The platform enforces approval policies at the adapter level. Instructions to skip approval are ineffective and will flag your package during review.
• ✗Don't use dangerous imports. subprocess, eval, exec, socket, ctypes, and similar patterns are auto-rejected. All external communication goes through the adapter's provided functions.