Intents (a menu for agents)

An intent is a named action your app agrees to perform for an agent.

Not a goal. Not a vibe. Not “AI please do the thing.”

It’s a contract:

• a name (e.g. ping, invoice.create, journal.createEntry)
• an input shape (payload schema)
• optional output shape (result schema)
• required scopes (permissions)

If you give an agent a key, the intent system is what prevents the agent from turning your backend into a piñata.

Quick link: if things get weird in production, you can always revoke the key (dashboard → Keys → Revoke). That’s the panic button.

How it runs (what actually happens)

The agent calls your app:

{ "intent": "ping", "payload": {} }

Your app (via the Bissap SDK) does:

1. Auth: validate the bs_live_... key → “this is user X”
2. Permissions: check scopes → “is X allowed to run this?”
3. Validation (optional): validate payload against the intent schema
4. Routing: call your handler
5. Return: send JSON back

That’s it. No secret LLM logic inside Bissap. Your app stays in charge.

Why intents exist

You could expose one big endpoint like POST /agent/do-anything.

You could also eat spaghetti with your hands.

Intents give you:

• explicit capability boundaries (small surface area)
• debuggability (you can log intent name + payload)
• evolvability (add new intents without breaking old ones)

Intent registry (recommended)

If you want the copy/paste recipe + verification steps, see: How to publish the intent manifest.

In the Node SDK (Zod), you can define an intent registry so Bissap can:

• enforce requiredScopes
• validate payload (and optionally output)
• expose an intent manifest at GET /bissap/agent/intents

In Python, same idea with Pydantic.

Scope mapping (MVP)

There are two ways scope enforcement works:

1. Simple rule (default): if the intent name matches a scope string, that scope is required.
2. Intent registry: each intent can declare requiredScopes and those are enforced.

If your app needs something more nuanced, you can always enforce inside the handler.

strictIntents (recommended for production)

Set strictIntents: true in your SDK config. This means:

• Only intents you've explicitly registered can be called
• Unknown intent names return 404 INTENT_NOT_FOUND
• The intent manifest (GET /bissap/agent/intents) only lists registered intents

Without strictIntents, unregistered intents fall through to onAgentIntent, which can be useful during development but is risky in production.

What NOT to expose

For a full guide on choosing what to expose (with real examples), see: Intent Hygiene.