Agents (Preview)

An agent answers conversations for your business on the endpoints you give it, such as an email address. You write what it knows and how it behaves, publish that as a version, and Samva runs the published version on each reply.

Set up an agent in the dashboard

Open Agents in the dashboard and create an agent. Each step saves to the agent's draft, and nothing answers your customers until you go live.

1. Describe. Give your website or Instagram profile, your own description of the business (services, prices, hours), or both. Samva drafts the agent's name, instructions, and knowledge from them, using only facts it found and listing what it could not confirm. Edit the draft before you create the agent.
2. Try it. Chat with the agent as a customer would. It answers from the saved draft, sends nothing, and does not use connected tools, so it says what it would book instead of booking.
3. Connect. Choose the email addresses and WhatsApp numbers it answers on, and connect Google Calendar to let it book appointments.
4. Rules. Choose whether bookings and changes wait for your approval, the hours it offers appointments in, and how long it stays paused after a person replies in a conversation.
5. Go live. Start supervised, where each reply waits for a person to approve it in the mailbox, or fully on, where replies send. Going live publishes the draft as a version.

Trying the agent and drafting it from your business draw AI credits, like its replies do.

What an agent holds

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

A new agent starts in supervised mode on the standard model with no endpoints, so nothing is sent until you choose. An endpoint answers for one agent at a time.

Model usage draws your account's AI credits as the agent works.

Draft, publish, versions

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.

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.

Staff takeover

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 agent

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": "Front desk",
    "definition": {
      "instructions": "Answer booking questions politely and briefly.",
      "knowledge": "We are open Monday to Saturday. A haircut costs 600 rupees.",
      "endpointIds": [],
      "integrationIds": [],
      "mode": "supervised",
      "model": "standard",
      "approvalPolicy": "toolActions",
      "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 booking questions politely and briefly.",
      "knowledge": "We are open Monday to Saturday. A haircut costs 600 rupees.",
      "endpointIds": ["'"$ENDPOINT_ID"'"],
      "integrationIds": [],
      "mode": "live",
      "model": "standard",
      "approvalPolicy": "toolActions",
      "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.

Book on Google Calendar

Connect Google Calendar in the agent's Connect step to let it check your availability and book, move, and cancel appointments. Samva asks Google only for permission to read free and busy times and to manage events, and only when you connect; signing in to Samva never asks for calendar access. Through the API, add the integration's id to the agent's integrationIds and publish.

An agent with a connected calendar:

• offers times only inside its workingHours that are free on the calendar you chose;
• books only after the customer confirms a time, and changes or cancels only the appointments it booked for that customer;
• writes events without sending Google invitations; it tells the customer itself.

With approvalPolicy set to toolActions, each booking, change, and cancellation waits for a person to approve it in the mailbox, exactly as the agent proposed it; the agent tells the customer the team will confirm, and finishes once someone approves. You can also require approval for one calendar action, or turn it off, on the integration itself.

If Google stops accepting Samva's access (you removed it from your Google account, for example), the integration shows that it needs reconnecting and the agent stops offering calendar actions until you connect again.

Namespaces and keys

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.