upsertSiteAgent

utilitysince 0.2.7not for built apps

Client function: create-or-replace a site agent persona.

import { upsertSiteAgent } from 'flowstack-sdk'

Non-React client function. POST /api/v1/sites/{siteId}/agents. Upsert semantics matching the casino_create_agent MCP tool: posting an existing name replaces that persona wholesale. Use updateSiteAgent when you only want to change some fields.

Signature

upsertSiteAgent(credentials, siteId, agent, config?): Promise<ApiResponse<{ site_id: string; agent: SiteAgent }>>

Parameters

Param	Type	Notes	Description
`credentials`	`FlowstackCredentials`	required	The app owner's credentials (owner-scoped JWT).
`siteId`	`string`	required	The site/app id to register the persona on.
`agent`	`SiteAgentInput`	required	The full persona: `name` and `system_prompt` are required; `capabilities`, `tools`, `description`, `route_when`, `cost_hint` and `model` are optional.
`config`	`FlowstackClientConfig`	—	Client config (baseUrl, tenantId as needed).

Returns

Field	Type	Description
—	`Promise<ApiResponse<{ site_id: string; agent: SiteAgent }>>`	The stored persona.

Examples

const res = await upsertSiteAgent(credentials, siteId, {
  name: 'coach',
  system_prompt: 'You analyze the user’s training log and suggest next week’s plan.',
  capabilities: ['data_access'],
  model: 'claude-sonnet-4-6',
});

WarningOwner/management operation — call it with the app owner's credentials from a builder/dashboard/server context, not from inside the generated app's end-user runtime. builtAppSafe is false.

WarningThis is a replace, not a patch. Re-posting a persona with fields omitted drops those fields — a partial upsert silently wipes capabilities, tools or model. Use updateSiteAgent for field-level edits.

upsertSiteAgent

Signature

Parameters

Returns

Examples

See also