Targeting Custom Agents (Built Apps)

guide

Built apps target an agent they create via casino_create_agent by passing its registered name as persona — a target is required for app-scoped users or they get a 403.

For built apps, the agent you target is one you create via casino_create_agent. There are no pre-built ecosystem agents — you define the persona and capabilities, and the platform enforces them. (The SDK's dataScienceTemplate/marketingTemplate/supportTemplate are client-side config scaffolds, not registered agents.)

Create the agent once via MCP at setup time, then select it from your built app with the persona option. The registered persona's server-side definition is authoritative — capabilities/tools passed to useAgent are advisory and can only narrow within it, never widen.

Examples

Create then target a custom agent

// 1. Create your agent via MCP first (once, at setup time):
//    casino_create_agent(site_id, "support_bot", "You are a helpful support assistant...", capabilities=["data_access"])
//    OR for per-tool control: casino_create_agent(site_id, "support_bot", "...", tools=["query_mongodb", "count_documents"])

// 2. Target it from your built app:
const { query, messages, isStreaming } = useAgent(undefined, {
  persona: 'support_bot',             // must match the name you registered
  capabilities: ['data_access'],      // advisory — the registered persona's grant is authoritative
});

CriticalA target persona is required for app-scoped users (appScope set) — pass persona: '<registered name>'. Without a target, app-scoped users get a 403. The name must exactly match a casino_create_agent registration for your site. (targetAgents is a deprecated alias — see useAgent.)

Targeting Custom Agents (Built Apps)

Examples

See also