HTTP actions

An action is an HTTP request an agent may make during a conversation. You define the endpoint once, and the agent decides when calling it would answer the question.

Action fields

Everything the agent knows about your endpoint is on this form. The description is the important field: it is the only thing the agent reads when deciding whether this action is the right one.

tool_namestringRequired

Lowercase, no spaces. The agent refers to the action by this name in its own reasoning, so check_credit_balance reads better than tool2.

descriptionstringRequired

One sentence saying when to use the action, in the language your customers use. This is the biggest single lever on whether the action fires at the right moment.

endpoint_urlstringRequired

An absolute https url. Duvi uses it exactly as given. There is no path templating, so values are added as query parameters, headers or a body rather than substituted into the path.

methodenumDefaults to GET

GET, POST, PUT, PATCH or DELETE.

headersvalue[]

Sent on every call. Anything sensitive belongs here as a stored key rather than a fixed value, so Duvi never shows the secret again after you save it.

query_parametersvalue[]

Appended to the url. Same shape as headers.

body_parametersvalue[]

Sent as JSON. Ignored on GET, so a GET action carrying body parameters is almost always a mistake.

integration_idstring

Links the action to an integration that signs the call in as the customer. Set this when the endpoint returns data belonging to one person. See Call your API as the customer.

Value sources

Every header, query parameter and body field takes its value from one of five places. This setting decides what the agent is allowed to supply.

value_type	value holds	Filled by
`static`	A literal string	You
`reference`	One of the type names below	The agent, in conversation
`secret`	The id of a stored key	Duvi, at call time
`identity`	No value field at all	Duvi, from the verified customer
`client`	The name of a widget page variable	Your embedding page

Duvi withholds a tool that requires a client value when the embedding page did not supply that variable. Page variables are visible to the visitor and provide context, not verified identity. See Page variables.

Duvi adds one header of its own on every call, x-chat-id, carrying the id of the conversation the call came from. Use it to correlate your logs with a chat.

Reference value types

A reference value is typed. The agent keeps asking until what it has fits the type, and Duvi never makes the call with a half filled field.

string, number, boolean, date, uuid, email, url, array[string], array[number], array[boolean], array[object].

the definition

{
  "tool_name": "check_credit_balance",
  "description": "looks up how many credits an account has left",
  "endpoint_url": "https://api.duvi.ai/v1/credits",
  "method": "GET",
  "headers": [
    { "key": "Authorization", "value_type": "secret",
      "value": "6f1c9a2e-..." },
    { "key": "X-Customer-Id", "value_type": "identity" }
  ],
  "query_parameters": [
    { "key": "account_id", "value_type": "reference",
      "value": "string" }
  ]
}

what the agent sends

GET /v1/credits?account_id=A-40192
Host: api.duvi.ai
Authorization: Bearer <stored key>
X-Customer-Id: <identity>
X-Chat-Id: 4f2ab8c1-...

Failure behaviour

The agent sees the status and the body. It tells the customer something went wrong rather than inventing a result, so a readable error body produces a better recovery.

Response	What the customer hears
`2xx`	The answer, phrased in the agent voice.
`4xx`	That it could not look it up, plus one attempt to correct the input if a field looks wrong.
`5xx`, timeout	That the system is unavailable, and an offer to take details instead.
No token	With an integration set, a failed token exchange stops the call before it is made.