Agent workspace, automations, and app API

An agent is a saved set of instructions, knowledge, tools, and limits. An automation is a task assigned to that agent on a schedule. The same agent also accepts manual and app requests. There is no separate general-purpose Workflows product.

Action	What you do
Build	Set instructions, upload knowledge, configure optional tools, and save
Try it	Give the agent one task and inspect its result
Automate	Set a recurring task, frequency, time, and time zone
Business records	Review leads, approve quotes and follow-ups, reply to visitors and manage appointments
Website & API	Publish website chat, connect your APIs, or create an app key
History	Review manual, scheduled, and app runs, their results, errors, and costs

Organization members can view agents and nonbusiness run results. Business records and business-run output require an owner or admin. Owners and admins can change agents, start runs, create keys, and manage automations. Saving checks the current revision so an older browser tab cannot overwrite newer changes.

Build your own agent

Choose Agents → Create agent, write your instructions, then configure knowledge, tools, and limits. Optional business capabilities add lead records, quotes, website conversations, appointments, and monitoring actions. They do not supply or replace your instructions. You can import your own JSON configuration or your own repository under Custom code. See the quickstart.

Files and web sources

Use UTF-8 TXT, Markdown, CSV, or JSON. A file is limited to 100 KB; instructions and knowledge together to 200 KB; an agent to 10 sources. Convert PDF/DOCX files to text first. The agent receives the full supplied reference text; this is not a large-document indexing or search service. A URL source must return public HTTPS text or JSON within 64 KB. Private, loopback, and local-network addresses are blocked, including after redirects. URL failures make the run fail visibly.

Tools

The current date and time are built in. Configure up to five HTTP tools with a unique name, description, fixed URL, and GET or POST method. GET reads that URL; POST sends the JSON body chosen by the agent. Only configured endpoints can be called. Tools do not receive your platform session, app key, or other credentials. A write tool may have effects before a cancellation arrives; inspect the target system before retrying an interrupted run. A failed write request is never silently replayed by the managed runner.

Scheduling

Automations use the latest saved configuration at the time they are queued. Each queued run then keeps its own configuration snapshot. Times use the selected IANA time zone, such as America/New_York. A missing daylight-saving clock time is skipped; a repeated clock time runs once. After downtime, at most one missed occurrence is caught up before the schedule advances to its next future time. A paused or deleted automation cannot start further execution steps.

Pause an entire agent to stop further work from all triggers. Revoking an app key stops requests and future steps from that key. Work already sent to an endpoint cannot be recalled. Archiving pauses automations, revokes keys, and retains run records.

App API

Create a key in Website & API. It grants run creation and result reading for one agent only, expires after the selected period, and is shown in full once. Keep it on your server; it is different from a general platform or model API key.

POST /v1/agents/AGENT_ID/runs
Authorization: Bearer AGENT_KEY
Idempotency-Key: your-stable-job-id
Content-Type: application/json

{"input":"Summarize the supplied knowledge."}

The standard response envelope contains data.run and data.pollUrl. HTTP 202 means accepted. Poll GET /v1/agents/AGENT_ID/runs/RUN_ID with the same bearer key. Terminal states are succeeded, failed, cancelled, and interrupted. Read run.output, run.error, and run.costCents. Keep the run ID on your side.

A request key is 8–128 letters, numbers, periods, underscores, colons, or hyphens. Reuse it with the same input after a network failure; conflicting input returns 409. Input is limited to 16,000 characters. Up to 20 runs can be queued or running per organization. Runs for the same organization or payer execute serially. A run key can read this agent’s results; use separate agents for data that requires separate access boundaries. Business-record permissions are optional and include workspace-wide leads, so grant them only to trusted server applications. Different runs do not automatically share chat memory.

Business records API

All requests use an agent bearer key. Existing keys have only the runs scope. Explicit records:read permission enables:

GET /v1/agents/AGENT_ID/records/leads?offset=0
GET /v1/agents/AGENT_ID/records/quotes?offset=0
GET /v1/agents/AGENT_ID/records/conversations?offset=0
GET /v1/agents/AGENT_ID/records/appointments?offset=0

Responses contain data.records (up to 50) and data.hasMore. Increment the offset by 50. Leads are shared across the workspace; other records belong to the selected agent.

Explicit records:write permission enables these operations:

POST /v1/agents/AGENT_ID/leads
Content-Type: application/json

{"name":"Customer name","company":"Their business","email":"customer@example.com","notes":"Asked about service"}

PATCH /v1/agents/AGENT_ID/leads/LEAD_ID
Content-Type: application/json

{"revision":1,"stage":"replied"}

Stages are new, qualified, contacted, replied, won, lost, and do-not-contact. The current revision comes from the record. A conflict returns 409; reload before applying a deliberate change. A reply/closed/opt-out stage cancels unsent follow-up drafts. A message already submitted to an API cannot be recalled.

POST /v1/agents/AGENT_ID/quotes
Idempotency-Key: your-stable-quote-request
Content-Type: application/json

{"leadId":"LEAD_ID","title":"Service quote","items":[{"itemId":"SAVED_SERVICE_ID","quantity":2}]}

The API calculates totals from the saved price list and creates a draft. It rejects client-supplied prices or totals. A workspace owner or admin approves and shares it in the dashboard. Shared links are private capabilities: anyone holding a link can review and accept that quote. Voiding an unaccepted quote disables its link.

Your API connection contract

Create a connection with an exact public HTTPS endpoint and an optional credential header (Authorization, X-API-Key, or X-Subscription-Token). Include the complete header value, such as Bearer YOUR_TOKEN. Select the saved connection in Business setup. Changing a credential’s endpoint requires entering it again. Calls are DNS-pinned, TLS verified, limited to 10 seconds, and never redirect credentials or retry writes. Requests are limited to 32 KB and responses to 128 KB.

Each call is a POST with an Idempotency-Key header:

{"schemaVersion":1,"operation":"upsert_lead","data":{"id":"LEAD_ID","revision":2,"name":"Customer name"}}

Connection	Operation and request data	JSON response
Search	find_prospects: business, industry, location, criteria, limit	results: up to 20 objects containing url, title, optional description
CRM	upsert_lead: saved lead ID, revision, contact and source fields	accepted: true, optional id
Delivery	send_followup: id, to, subject, body	accepted: true, optional id
Calendar	availability: from, until, durationMinutes, timezone	slots: up to 500 objects containing ISO start and end
Calendar	create_appointment: id, title, start, end, timezone, contact	accepted: true, optional id
Support	create_ticket: conversationId, messages	accepted: true, optional id
Monitoring	health_checks: empty data object	checks: up to 20 objects containing name, status (ok, warning, error, unknown), detail

Calendar slots must match the configured duration and hours. Your calendar API must atomically reject a booking that is no longer available. Native holds prevent concurrent SetCloud bookings, but cannot reserve a slot in another system by themselves. Cancel externally connected appointments in that calendar first, then record the cancellation in SetCloud. Native appointments can be cancelled directly.

A lost acknowledgement becomes unknown, even if the remote service acted. SetCloud never resends that intent automatically. Check your API using the request reference, then record the checked outcome and evidence in Business records. Use API activity for lead syncs and support tickets. Use the Follow-ups or Appointments tab for those actions so the matching record is updated too. Reconciliation does not send a request or automatically retry a failed action.

Lead sync sends each saved revision once per agent and connection. Editing the lead allows a later sync to send its updated details; repeating an unchanged revision returns its recorded outcome. An agent with a pending or unconfirmed lead sync waits for that outcome to settle before sending more leads. Your API should upsert by the stable lead ID and use its revision to avoid replacing newer data with older data.

The connection contract is intended for clients’ own website and business APIs. To call a service with a different schema, add a small adapter in your application; a central verified integration app is not part of this setup.

Website conversations

Only published agents on an exact allowed HTTPS origin can create visitor sessions. The embed uses a separate, short-lived visitor token and does not send dashboard cookies or app keys. Each conversation has its own messages and current contact. Visitor actions cannot read the workspace lead list, call private HTTP tools, approve quote drafts, send follow-up messages or confirm another visitor’s appointment.

The rolling 24-hour allowance reserves full run limits atomically. Interrupted or failed runs keep that reservation for the window because an external outcome may be uncertain. Additional limits: 10 sessions per IP per agent per day, 1,000 sessions per agent per day, 50 visitor messages per conversation, and three messages per ten seconds. IP limits and budgets reduce abuse; they do not verify visitor identity. Do not put account-specific secrets in a public assistant’s knowledge.

A website chat session lasts 24 hours and is stored in the visitor’s browser tab. Team replies appear in that same session. No external email delivery is implied. Unpublishing or pausing the agent stops future visitor actions and model steps.

Costs and recovery

The per-run limit is checked conservatively before each model step, alongside credits, credit onboarding, suspension, and spending controls. Requests already performed are recorded and charged once using a stable usage reference. Unsettled usage blocks further paid work until settlement succeeds. Interrupted or ambiguous external actions are not replayed automatically. History preserves the outcome for review, including partial usage costs on failed runs.

Repository agents

Custom code retains repository import, configuration in agent/setcloud.json, repository schedules under agent/schedules/, deployments, and connected code-review tasks. Deployments need your repository’s runtime contract and linked secrets. The earlier framework-based templates are retired from new-agent creation; existing repositories keep their original license, code, and behavior.

A custom runtime is responsible for its own request authentication, tool controls, conversation checkpoints, and runtime results. Its deployment and connected-review history remain in the custom-code workspace. See code reviews and the retained legacy runtime guide.