Samva Agents

Samva Agents answer customer conversations for your business on the endpoints you give them, such as an email address. Support teams, store owners, and service businesses that book appointments all use them the same way: you write what an agent knows and how it behaves, publish that as a version, and Samva runs the published version on each reply.

Create an agent in the dashboardCopy Anchor Link

Open Agents and choose Create agent. Pick a preset, Appointment booking or Blank, then optionally describe your business (services, prices, hours) and give your website. Samva drafts the agent from the preset's instruction sections and your words, using only facts it found and listing what it could not confirm. Write nothing and the preset itself is the draft. Drafting is free.

The agent is created and opens in its editor. Nothing answers your customers until you go live.

An agent page has three tabs:

• Editor holds every setting in one column, with a customer preview beside it.
• Tests keeps the conversations you saved and replays them.
• Overview shows what the agent still needs and how channels, the agent, tools, and knowledge connect.

Edit the agentCopy Anchor Link

The Editor tab is one settings column. Changes stay in your browser until you choose Save, which writes everything at once. Publish saves and publishes in one step; the first time it reads Go live.

• Name. What your team sees in the dashboard and in Mail.
• Instructions. Shown as one card per ## section. Edit a section on its own, or edit the whole text. To change the instructions in words, use the sparkle button to ask for a change, such as "Waive the late fee once per customer". Samva proposes edits to specific sections, and you Keep or Undo each one, or choose Keep all or Undo all. A proposal changes nothing until you keep it.
• Model and spend. The model picker, Thinking, and the monthly spend cap.
• Answers on. The email addresses the agent answers on, and the WhatsApp numbers when your organization has WhatsApp.
• Knowledge. What the agent reads on every reply, described below.
• Tools. Which connected integrations the agent may use, what it may do with each, and which actions wait for a person. See what an agent may use.
• Rules. What the agent may do on its own and what waits for you, described under Decide what needs you. Also the appointment hours, and how long the agent waits after your team replies in a conversation.

Decide what needs youCopy Anchor Link

Rules opens in one of two views over the same rules.

• Auto is where a new agent starts. Lookups go ahead, replies and changes go ahead when your instructions cover them, and anything that moves money or can't be undone waits for a person. Write What needs you in your own words, such as "Refunds over ₹500 and complaints about staff wait for me. Booking and moving appointments is fine." Anything these instructions don't cover waits for you, with the reason it was held.
• Custom is the rule table. Each row, for lookups, replies and changes, or actions that can't be undone, chooses Run, Auto, Ask a person, or Never. Add rule adds a row for one kind of action, such as replies or tool calls, or for one connected app. A row marked Floor is binding: a narrower rule cannot loosen it.

Start from copies a preset into the rules: Auto, Approve every reply, or Send every reply. Your own rows and your What needs you text stay. Rule changes are part of the draft, so they reach live replies when you publish.

Always allowed lists the actions an organization owner or admin approved with Always allow in Needs you. These apply to the live agent at once. Remove one and those actions wait again. Saving a change to the agent's rules clears the list.

KnowledgeCopy Anchor Link

Knowledge sources belong to the agent's namespace, or to organization level when the agent has no namespace. Add a website or upload a PDF, Word, text, or Markdown file once, then use its checkbox to choose which agents in that same namespace can read it. Save keeps the selection in this agent's draft; Publish makes it available to live replies.

Each source shows whether it is being read, updating, ready, or could not be read. Sync now reads it again. Clear its checkbox to detach it from this agent. Remove deletes the source and Samva's copy for every agent that uses it. See Knowledge limits for source, file, searchable-content, and refresh limits.

To use a Shopify catalog, choose Add, then Shopify store. The chooser lists your connected stores. Choose Add store beside the store you want to attach. Its Shopify store source contains active products and store policies, and can be used by other agents in the same namespace. Save or publish the attachment like any other source selection.

If a store needs product or policy permission, choose Allow access. For an expired connection, choose Reconnect. Save your editor changes first: authorization takes you to Shopify and then returns you to the agent editor. An organization administrator can also choose Connect store to connect another store. After returning, open the chooser and add the store to the agent. See Connect Shopify for the access requirements and how product knowledge differs from live order tools.

Notes hold prices, policies, and answers in your own words, for facts that live in no source.

Test as a customerCopy Anchor Link

The preview beside the editor is always open. Chat with the agent as a customer would. It answers from your unsaved draft, so you can change an instruction and see the effect before saving. Tools it may use answer with sample data and change nothing, so it says what it would book instead of booking. Nothing is sent. Each reply shows what it followed, read, and used. Previews are free and always run on the default model, whichever model the agent uses once live.

Save as a test keeps the conversation and the expected decision for each proposed action: allow, hold, or refuse. A reply expectation can also keep the reply text.

TestsCopy Anchor Link

The Tests tab lists your saved tests. Run all replays every test and Run replays one, each on the editor's current draft, unsaved changes included. A test shows Changed since approved when its action decisions differ from the expected ones. If the new decisions are what you want, choose Approve new; delete a test you no longer need. Running tests is free.

Expand a test to see its expected decisions. Each one reads Goes ahead, Waits for you, or Refused, and an expected reply keeps its text. Change any of them and choose Save to make them the test's expectations.

When you publish changes to a live agent that has saved tests, Publish first compares every test under your draft and under the live version, and lists each decision that changes, such as "Reply: Waits for you → Goes ahead". A change that lets an action go ahead is marked. Choose Publish to go ahead, or Review tests to look first. Going live for the first time publishes straight away.

Run simulationsCopy Anchor Link

Choose Run simulations to play every saved test as a conversation against your current draft, including unsaved changes. An AI customer continues the conversation, then a judge scores it against the test's expected decisions for its saved turn and explains the result. Later turns contribute to the conversation score. Results identify actions wrongly allowed and actions wrongly held. Tools answer with sample data and change nothing. Nothing is sent to customers.

The run continues when you leave the tab, within limits on conversation turns and elapsed time. Return to Tests to see its progress, each test's score and reason, and expand a row to read its conversation. A run keeps the draft and tests it started with, even if you edit or delete a test later. If a run cannot finish, its scored results remain available and you can run simulations again.

Go live and Publish warn when the latest simulations contain failures or did not finish. The warning never blocks publication. Simulations use Standard, with a monthly allowance; additional usage is billed by use. Preview replies and saved-test replays remain free.

To compare a draft with the published version, call POST /v1/agents/{id}/tests/rerun with the agent's name and full definition. Each result includes publishedDecisions, draftDecisions, and changedDecisions. The same operation is available as agents.rerunTests in the SDK and samva agents tests rerun <agent-id> --data '<draft JSON>' --json in the CLI. A draft without a published version returns publishedDecisions: null. A comparison that reaches its time limit returns an error; run the tests individually or shorten their conversations before retrying.

OverviewCopy Anchor Link

The Overview tab starts with a checklist of what the agent still needs: instructions, a channel, knowledge, trying it in the preview, and going live. Below it, a map shows channels feeding the agent, with its model, and the tools and knowledge it uses. Each card opens its section in the editor.

Ask your managerCopy Anchor Link

Owners have a manager for their organization's agents. Open it with Ask your manager on the Agents page, or the sparkle button on an agent's page; it docks beside the page and stays open as you move between them. Ask how your agents are doing, which conversations need a person, or why an agent answered as it did. Type @ or press + to point it at an agent or one of its recent conversations by name. Each reason in an answer is marked Recorded when it comes from what Samva kept about the reply, or Inferred when the manager is reading the conversation. Reports cover shared mailboxes; personal mailbox conversations stay private.

The manager proposes changes; it never makes them on its own.

• Instructions or notes. The proposal shows in the panel with Review, which opens the agent's editor with the change in the same Keep and Undo review as the sparkle button. The review says whether the proposal was made for the saved draft or an earlier one; for an earlier draft it shows only the parts the manager changed. Nothing changes until you keep a change and save.
• Sending a held reply or pausing an agent. The proposal shows the exact reply or the pause, with Approve and Deny. Dashboard chat does not approve actions; use the confirmation control. On email or WhatsApp, reply with the exact confirmation command shown with the proposal. Only the owner who asked can approve it. A proposal left waiting expires; ask again for a fresh one.

If a confirmation stops before its result is known, inspect the actual reply or agent first. Once recovery is available, the owner who requested it can choose Mark done or Mark not done in the manager panel. This records what happened without repeating the action. On email or WhatsApp, use the exact Resolve command shown in the original thread.

A paused agent stops starting replies, and its page and the agents list show Paused by an owner. Choose Resume on the agent's page to let it answer again. It automatically picks up its open, unanswered shared-mailbox conversations that staff do not hold. You do not need to hand those conversations back in Mail.

Owners can also message the manager from their verified account email on a business email address answered by an agent. Incoming email must authenticate successfully; an unverified or unknown sender continues to reach the customer agent. Other members, including Mail-seat users, also continue to reach the customer agent. WhatsApp follows the same routing from a verified owner phone on your business's existing number, when WhatsApp is enabled. There is no separate manager number. Replies stay on the channel and thread where you asked.

To verify your WhatsApp identity, open Settings → Profile, save your phone with its country code, then choose Create verification command. From that phone, send the exact command to the business number shown. Commands expire after 10 minutes; creating another replaces the previous one. Editing your profile invalidates an outstanding command, and changing your phone clears its verified status. Only organization owners can verify a phone for manager access.

Only the owner who requested an operational proposal can confirm it, in the same thread. Use the exact Confirm command in the reply. Instructions and knowledge always go through Review in the dashboard editor; confirming a message cannot apply them. Manager channel conversations are separate for each owner and thread.

Manager answers run on Standard and draw from your organization's AI usage by use, like Ask AI. They do not add the fee charged for sending a customer reply.

As an owner, turn on Daily agent summary in the manager panel to receive a daily email about your agents, including conversations that need a person and replies awaiting approval. Owners can also choose their preference in Settings → Profile → Agent notifications. Turn it off in either place to stop receiving summaries.

Before choosing WhatsApp for the day, Samva checks that your phone is verified, the business number can send, and its utility template is usable and approved. Otherwise, it chooses your verified email.

What an agent holdsCopy Anchor Link

An agent keeps one definition, and a version is a published copy of it.

A new agent starts in Auto (the samva/auto preset), on the standard model at auto reasoning with no endpoints, so nothing is sent until you choose. An endpoint answers for one agent at a time.

Knowledge limitsCopy Anchor Link

Knowledge sources and agents must belong to the same namespace, including organization level. Attach the same source to several agents in that namespace through knowledgeSourceIds; publish an agent to use its changed source selection in live replies. Sources have no sharing option. A namespace key lists and manages only its own sources. A key that is not confined can add a source with namespaceId and filter the source list by that field.

Use samva knowledge list --namespace <namespace-id> to list sources, add-website --url to add a website, and add-file --media-id to add a ready attachment upload. Both add commands accept --namespace. The hosted MCP tools are knowledge_list, knowledge_get, knowledge_add_website, knowledge_add_file, and knowledge_sync.

Samva divides a source's text into searchable passages, small sections that an agent can use to answer a question. A Shopify store's active products and policies share that source's passage limit. If a Shopify catalog exceeds either limit, the refresh fails and the source keeps any existing copy.

Uploaded files are read when added and again when you request a sync. Websites and Shopify stores also refresh automatically; product changes trigger a Shopify refresh. A source keeps answering from its current copy while a new one is read.

Adding, reading, and refreshing knowledge sources is free. Live agent replies are billed separately for the reply fee and model use described under Choose a model.

Agents in personal mailboxesCopy Anchor Link

Your personal mailbox admits an agent only when you grant it access. Its replies follow the same decision rules as replies in shared mailboxes.

In a personal mailbox, the agent remembers each correspondent separately for that mailbox. These memories stay private to the mailbox, including when the person is also an organization contact. The agent reads its selected knowledge sources from the same namespace alongside those memories. It never adds personal correspondence to the organization's contact memories or shares it with other mailboxes. Removing the personal mailbox erases its saved conversations and correspondent memories.

In shared mailboxes, agents share memories about the same organization contact. Each mailbox keeps its own conversation and staff takeover.

Choose a modelCopy Anchor Link

An agent runs on one of two aliases or on a model you pin. standard, the default, is quick and capable for everyday replies. max gives the best-quality replies and needs a paid plan. Both aliases follow whichever model Samva points them at, so they improve without you changing the agent.

On the Growth and Scale plans you can pin a specific model instead. Set definition.model to a catalog model id, or choose the model in the editor's Model and spend section. GET /v1/agents/models lists every choice: the two aliases first, then each catalog model by name. Each entry has the model it runs, its context window, the kinds of input it reads, its price per million tokens, and access, which is included or upgrade when your plan does not run it. The response also carries replyFeeDollars, the fee every sent reply adds to its model use.

curl https://api.samva.dev/v1/agents/models \
  -H "x-api-key: $SAMVA_API_KEY"

definition.reasoning sets how hard the model thinks before it answers. auto, the default, lets Samva choose for the model. low, medium, and high ask for a level; a model accepts only the levels it supports, listed in its reasoning entry with an estimate of a typical reply at each level, and a draft that names another level is refused when you save it. The dashboard offers the same levels in its Thinking setting.

Replace the draft with the model and level you want, then publish:

{
  "revision": "...",
  "definition": {
    "model": "<id from GET /v1/agents/models>",
    "reasoning": "medium"
  }
}

A real request sends the whole definition, as in Create and publish an agent.

If a model you pinned cannot run, such as one that was retired or blocked, has not been checked yet, or has left the catalog, the published version keeps answering on standard or max, whichever is closer in price, rather than going quiet. The version reports this in modelFallback: from is the pinned model, to the alias answering, reason is candidate, failed, retired, blocked, or missing, and since is when it began. The field is null while the version runs as published. Pin another model and publish to end the fallback.

What replies costCopy Anchor Link

Each reply an agent sends costs a reply fee of $0.018, charged when the reply sends, plus the model use that wrote it. A typical reply on standard costs about $0.02 in all. A reply that never sends, such as one a person rejects after a policy holds it, still pays the model use that wrote it, about $0.002 on standard, but no fee. The message a reply sends also draws sending credits, like any other message your mailbox sends: one per email, and a WhatsApp reply at the rate in Samva's fee by category.

Model use is charged at the model's list price plus 10%, so max and other pinned models cost more or less per reply than standard by what they use. A max reply needs about $0.57 of AI usage available to start. Replies draw AI usage, a dollar balance kept apart from the sending credits your emails draw, so an agent never spends the allowance your mail needs.

Set a spend capCopy Anchor Link

Each agent can have a monthly spend cap in dollars. Set monthlySpendCapDollars on the agent, in whole cents, in the editor's Model and spend section or with PATCH /v1/agents/{id}. A null removes the cap. The change takes effect at once, without publishing.

curl -X PATCH https://api.samva.dev/v1/agents/$AGENT_ID \
  -H "x-api-key: $SAMVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "monthlySpendCapDollars": 25 }'

With the CLI, set or remove the cap without publishing:

samva agents update "$AGENT_ID" --monthly-spend-cap 25
samva agents update "$AGENT_ID" --remove-spend-cap

Spend counts the agent's model use and its sent replies in the current calendar month (UTC). The agent's spend reports it: month, spentDollars, and capReachedAt. When spend reaches the cap, the agent pauses and capReachedAt records when. Conversations it would have answered wait for your team until the month turns, or until you raise or remove the cap. The agent page shows the pause with how much the agent spent; a cap pause sends no email, because the cap is a limit you set on the agent.

An agent paused on a pinned model can keep answering on Standard instead. Use Standard in the dashboard, or POST /v1/agents/{id}/continue-on-standard, publishes the live version again with its model set to standard, then removes the cap. The draft is left as it is, so changes you have not published stay unpublished.

curl -X POST https://api.samva.dev/v1/agents/$AGENT_ID/continue-on-standard \
  -H "x-api-key: $SAMVA_API_KEY"

When AI usage does not cover a replyCopy Anchor Link

The agent pauses when your AI usage cannot cover its next reply. Owners and admins receive one email per pause, and the agent page, the agents list, and affected Mail threads show the pause and when it began. An agent at its cap shows the cap pause instead, because the cap holds conversations before AI usage is checked; once the cap is raised, an AI usage pause shows again until the agent can start its next reply. Only owners see billing and AI usage pack links; everyone else is asked to contact an owner. Customer messages that the agent cannot answer still notify the people who read that mailbox, and your team can reply in Mail. Sending uses separate credits and remains available.

An owner can buy an AI usage pack or review billing to restore the allowance. The pause clears when the agent can start its next reply. Buying AI usage does not itself replay unanswered messages; a new customer message or a hand-back to the agent can start its next turn. A conversation held by a person leaves the pause unchanged. A model unavailable on your plan does not trigger a pause email, because buying AI usage cannot enable it.

Draft, publish, versionsCopy Anchor Link

An agent holds a draft you edit and published versions that answer. PUT /v1/agents/{id}/draft replaces the whole draft, and POST /v1/agents/{id}/publish turns it into the next immutable version. Both take the revision from your last read of the agent. If the agent changed since, the request fails with ConflictError (HTTP 409): read the agent again and retry.

Use the CLI to read, edit, replace, and publish a draft. get --json returns the full agent in data; extract data.draft as the definition file, and keep the revision from the same read:

samva agents get "$AGENT_ID" --json > agent.json
jq .data.draft agent.json > draft.json
# Edit draft.json, then replace the whole draft.
samva agents draft replace "$AGENT_ID" \
  --revision "$(jq -r .data.revision agent.json)" --file draft.json --json > updated-agent.json
samva agents publish "$AGENT_ID" \
  --revision "$(jq -r .data.revision updated-agent.json)"

draft replace --file - reads the definition from stdin. Both mutations support --dry-run to preview without requests. Omit --revision on publish to read and publish the agent's current draft. Rename an agent with samva agents update "$AGENT_ID" --name "Shop assistant"; renaming takes effect without publishing.

A published version answers each conversation from that conversation's next agent reply. A reply already running finishes on the version it started on. Publishing a draft identical to the newest version changes nothing, and the response reports published: false.

Listing the versions returns each version number and publish time. Reading one version returns the definition it published.

Automatic mail and conversation limitsCopy Anchor Link

An email starts an agent reply only after its spam and virus scans pass and SPF or DKIM passes, with no DMARC failure. Mail without those verdicts stays outside agent turns and draws no AI usage.

Agents skip automatic responses, including out-of-office replies, delivery status messages, and read receipts. They also skip null return paths, common automated senders, mailing-list messages carrying List-Id or List-Unsubscribe, report messages, and mail marked with Precedence: bulk, list, or junk. Agents require an authenticated From domain and refuse ambiguous From headers. Agent replies honor Reply-To only for an authenticated From; otherwise they use From. A customer message that arrived before that mail is still answered. Agent email replies carry Auto-Submitted: auto-replied so other mail systems can recognize them as automatic.

Once a conversation has 8 agent reply or new-message proposals in a rolling 60-minute window, its next automatic turn is held for staff. The agent answers that conversation again after the hold lapses, once the window no longer contains those proposals. Other conversations continue. Handing the conversation back does not bypass this limit while the window still contains those proposals.

Staff takeoverCopy Anchor Link

When a person replies in a conversation, the agent pauses in that conversation. It answers again when the person hands the conversation back, or when takeoverTimeoutMinutes pass after the person last acted, whichever comes first. Other conversations are unaffected.

Create and publish an agentCopy Anchor Link

Create the agent with a first draft. Omit definition to start from the defaults.

curl https://api.samva.dev/v1/agents \
  -H "x-api-key: $SAMVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support",
    "definition": {
      "instructions": "Answer questions about plan limits and refunds politely and briefly. Offer an onboarding call when the customer asks.",
      "knowledge": "Customers write to support@acme.dev. The Pro plan includes 5 projects. Refunds are available within 14 days of the charge.",
      "endpointIds": [],
      "integrations": [],
      "policy": { "presets": [], "rules": [{ "match": {}, "decide": "person" }] },
      "model": "standard",
      "reasoning": "auto",
      "workingHours": null,
      "takeoverTimeoutMinutes": 30
    }
  }'

The response carries the agent's id and revision. Replace the draft to name an endpoint and go live, passing the revision you read.

curl -X PUT https://api.samva.dev/v1/agents/$AGENT_ID/draft \
  -H "x-api-key: $SAMVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "revision": "'"$REVISION"'",
    "definition": {
      "instructions": "Answer questions about plan limits and refunds politely and briefly. Offer an onboarding call when the customer asks.",
      "knowledge": "Customers write to support@acme.dev. The Pro plan includes 5 projects. Refunds are available within 14 days of the charge.",
      "endpointIds": ["'"$ENDPOINT_ID"'"],
      "integrations": [],
      "policy": { "presets": [], "rules": [{ "match": {}, "decide": "run" }] },
      "model": "standard",
      "reasoning": "auto",
      "workingHours": {
        "timeZone": "Asia/Kolkata",
        "ranges": [{ "day": "monday", "opens": "09:00", "closes": "18:00" }]
      },
      "takeoverTimeoutMinutes": 30
    }
  }'

Publishing needs the revision the replace returned.

curl -X POST https://api.samva.dev/v1/agents/$AGENT_ID/publish \
  -H "x-api-key: $SAMVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "revision": "'"$NEW_REVISION"'" }'

If another agent already answers on an endpoint in the draft, publishing fails with ConflictError. Remove the endpoint from that agent first.

What an agent may use from an integrationCopy Anchor Link

An integration holds your connected accounts and its settings. It does not decide what an agent may do with it: each agent holds a grant for every integration it uses. A grant in the agent's integrations has two parts:

readOnly covers the tools that only look things up. In the editor's Tools section, choose All tools, Read only, or Choose tools for each integration. An agent offers, and can call, only the tools its grant covers on an integration that is connected. Two agents can use one integration differently: one may only check availability while another also books.

"integrations": [
  {
    "integrationId": "intg_...",
    "tools": { "kind": "all" }
  },
  {
    "integrationId": "intg_...",
    "tools": { "kind": "readOnly" }
  }
]

Each integration's page lists its tools, their default decisions, and its limits: Shopify, Google Calendar, and Linear.

A grant decides which tools the agent may use. The agent's policy then decides whether a permitted call runs, waits for a person, or is refused. Rules can match an integration app name, a tool, an action kind, an effect, a channel, or a subject. Each rule supplies either decide, a default a narrower scope can replace, or atLeast, a floor that remains binding.

"policy": {
  "presets": [],
  "rules": [
    { "match": {}, "decide": "run" },
    { "match": { "effect": "write" }, "decide": "person" },
    { "match": { "effect": "final" }, "decide": "person" }
  ]
}

New agents start in Auto: lookups run, writes including customer replies and bookings go to the judge, and actions that can't be undone or move money wait for a person. The judge uses the preset guidance, your organization's and mailbox's instructions, the agent's What needs you text, and the matching rule's note. It allows an action only when the instructions cover it; uncertainty, invalid answers, and timeouts hold the action. Customer messages and tool output are evidence, never permission to act. Judge usage draws on your organization's AI credits; a held reply adds no reply fee.

Presets copy rules and guidance into the agent. Updating a preset does not change agents that already applied it. Approve every reply and Send every reply fill the reply rule; Start presets also include the guidance for their task.

The agent can call hand_to_team with a reason and an optional draft reply. This always creates a held handoff decision and hands the conversation to staff. Staff can read the reason and draft before replying. Mailbox owners receive an email with the reason and a link to the conversation. Staff who have enabled web push also receive a handoff notification.

When approving a held action, the API accepts always: true to add an allow rule for that actor. Remembering an allowance for a hosted agent or API key requires an organization owner or admin. Broader safety floors still apply. Saving a different agent policy revokes its remembered allowances; other draft edits retain them. The CLI exposes the same choice with --always. An agent's always-allowed rules live in its own policy scope: read them with GET /v1/policies/agent/{agentId} and clear them with DELETE /v1/policies/agent/{agentId}.

run allows an action, person holds it, and never refuses it. model asks the judge, which can only allow or hold. When judging is unavailable, the action holds with reason judgeUnavailable. A rule cannot bypass a tool's safety checks or widen an integration grant. Organization and mailbox floors also apply. See decision rules.

Each held call appears in Needs you with its decision and exact arguments. After a person approves, the agent runs that call once and continues. If the person denies it, the agent continues without running it. A temporary interruption does not lose the decision. Replies use the same policy and carry their own decisions.

Once an agent has read results from an integration in a conversation, its replies there wait for a person, even when the reply rule would send them, unless an organization owner turned on Answer without approval for that integration. The held reply names the integration whose data it used, and Always allow does not lift the hold. Each integration's page explains the setting. After a conversation reads any integration's results, the agent saves no new customer facts from it to shared memory, so another conversation never answers from that data without the hold.

Publishing validates every grant. If a grant names an integration that is not installed in your organization, or a tool its app does not have, the request fails with ValidationError (HTTP 422) on the field definition.integrations, and nothing is published. Creating an agent, or saving a draft that adds a grant, fails the same way when that grant names an integration that is not installed, and the draft keeps its earlier grants.

When an integration is removedCopy Anchor Link

Removing an integration, or disconnecting the account it uses, also removes its grant from every agent's draft. The published version keeps the grant until you publish again, but the agent can no longer list or call that integration's tools: a call is refused, and the conversation's held actions for it are not run. Publish the agent to drop the grant from the live version too. The editor's Tools section shows when the live agent still lists a removed integration.

Connecting the account again installs a new integration with a new integrationId. Agents don't get access to it automatically: switch it on in each agent's Tools section, or add a grant for the new id to the agent's integrations, then publish.

Namespaces and keysCopy Anchor Link

An agent belongs to one namespace, chosen when you create it with namespaceId; it cannot move. A key confined to a namespace creates, reads, and edits only that namespace's agents. Grant a key the agents resource to let it manage agents.

Author newsletters with your coding agentCopy Anchor Link

Your coding agent can use hosted MCP to create a newsletter through newsletters_create, then read and edit its Markdown issues through the newsletter_issues_* tools. Use the newsletter ID for authoring and its topicId for subscriptions and campaign audiences. Newsletter authoring explains revision fences, saved commits, archives, and custom domains.

Conversation RetentionCopy Anchor Link

Deleting an agent removes its saved conversation state in the background while retaining contact memory; removing an inbox from the agent retains that state until the agent, inbox, contact, or workspace is deleted.

Forget Agent MemoryCopy Anchor Link

Forget refuses with HTTP 409 and code conversationHasPendingActions while a tool action is waiting for approval, approved but not executed, or executing with an unsettled outcome. Approve or deny waiting actions and let approved or running actions finish, then try again. A contact-wide forget checks every shared-mailbox conversation for that contact. The refusal erases nothing and publishes no forget barrier.

In Mail, open the conversation's ⋯ menu, choose Forget memory, and confirm. In a personal mailbox, only its owner can use this action. The agent forgets what it remembered about that person in that mailbox. In a shared mailbox, a collaborator or admin can forget the conversation; the contact's shared memory stays available to other conversations.

To forget a contact's agent memory across shared mailboxes, an organization owner or admin opens that contact in the dashboard and chooses Forget memory. This keeps the contact and leaves personal mailbox memories unchanged.

Forgetting keeps your mail, conversation and takeover state. The agent may learn again from mail it re-reads. An unanswered customer message can still receive a reply. API keys and agents cannot request forgetting; the dashboard assistant asks for approval before acting as the signed-in person. A pending-action refusal changes nothing; try again after the actions settle. For any other failed or interrupted operation, contact support before retrying so a partial erasure can be completed safely.