One-shot answers

View as Markdown

A one-shot ask sends one question and gets one answer, with no session to manage. The agent uses all of its settings — instructions, knowledge, tools and guardrails — so answers are the same quality as in a chat. Use it for help buttons inside your app, answers on product pages, drafting replies for your team, or any backend job that needs the agent’s knowledge.

A basic call

curl https://api.k-agent.kerneltics.com/v1/agents/store-assistant/ask \
  -H "Authorization: Bearer $KAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "How much is delivery?"}'

const res = await fetch('https://api.k-agent.kerneltics.com/v1/agents/store-assistant/ask', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KAGENT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ input: 'How much is delivery?' }),
});
const run = await res.json();
if (!res.ok) throw new Error(`${run.error.code}: ${run.error.message}`);

if (run.outcome === 'handed_off') {
  console.log('Passed to the team:', run.handoff.summary);
}
console.log(run.output_text);

import os, requests

r = requests.post(
    "https://api.k-agent.kerneltics.com/v1/agents/store-assistant/ask",
    headers={"Authorization": f"Bearer {os.environ['KAGENT_API_KEY']}"},
    json={"input": "How much is delivery?"},
    timeout=120,
)
run = r.json()
if not r.ok:
    raise RuntimeError(f"{run['error']['code']}: {run['error']['message']}")
if run["outcome"] == "handed_off":
    print("Passed to the team:", run["handoff"]["summary"])
print(run["output_text"])

The response is a run. Read output_text for the answer and outcome to know whether the agent answered or handed_off.

Request fields

Field	Type	Description
`input`	string or `[{type: "text", text}]`	The question. Up to 32,000 characters with a secret key, 4,000 with browser credentials.
`end_user`	object	`{external_id, name?, traits?}`. With a secret key the user is verified, which enables identity-bound tools and per-user memory.
`history`	array	Earlier turns from your own app, e.g. `[{"role": "user", "content": "…"}, {"role": "assistant", "content": "…"}]`. Used as text and marked as unverified, caller-supplied context.
`variables`	object	Values for the agent’s variables, including secret ones (used for this call only).
`allow_actions`	boolean	Default `false`: tools with side effects are not offered. Set `true` to allow them.
`store`	boolean	Default `true`. `false` keeps no transcript (see below).
`stream`	boolean	Stream the answer as Server-Sent Events.
`version`	integer	A published version to use instead of the latest.
`overrides`	object	Per-request changes the agent allows (see below).
`metadata`	object	Your own key–value pairs, returned on the run.
`wait_seconds`	integer	How long to wait for the answer (default 60, max 110) before returning `202`.

Who is asking

Pass end_user when you know the person. Verified one-shot calls can use HTTP tools that need identity — for example looking up this customer’s order — and they share the action memory and limits of that end user’s sessions:

{
  "input": "Where is my order?",
  "end_user": { "external_id": "cus_1042", "name": "Fahad", "traits": { "plan": "gold" } }
}

Actions are off unless you ask

Because one-shot calls are often automated, tools with side effects (create_ticket, HTTP tools with effect: "action", client tools) are removed by default. Read tools and handoffs always work. Send "allow_actions": true when the call should be able to act.

Private mode: `store: false`

With "store": false:

no messages are stored, and the run’s events are deleted when it ends;
run steps keep no arguments, results or summaries;
no message.created event is emitted, and webhooks carry no text;
GET /v1/runs/{run} returns only the status and usage;
client tools are not offered.

Usage is still recorded for billing.

Per-request overrides

An agent can allow some settings to change per call. List them in the agent’s overrides.allowed (and, for model, the models in overrides.models), then send:

{
  "input": "Summarize our return policy.",
  "overrides": {
    "dialect": "msa",
    "tone": "formal",
    "instructions_append": "Answer in at most three sentences."
  }
}

Allowed fields are dialect, tone, instructions_append, temperature, model, tools_disable and history_limit. The never-handle list, the escalation reply and tool grants can never be overridden, and only secret keys may send overrides; anything else returns 422 override_not_allowed.

When the agent hands over

Guardrails apply to one-shot calls too. A never-handle topic, or a question the agent cannot answer from what it knows, ends with a handoff that your team can see:

{
  "object": "run",
  "mode": "one_shot",
  "status": "completed",
  "outcome": "handed_off",
  "output_text": "Thank you for telling us. We've passed this to the responsible manager, who will contact you shortly.",
  "handoff": { "id": "ho_01k6rz6c8e0g2j4m6p8r0t2v4x", "reason_type": "liability", "summary": "Customer reports the perfume caused a skin reaction", "status": "recorded" }
}

For a liability case with an escalation reply configured, output_text is your reply, word for word.
There is no session to pause, so the handoff is recorded. It appears in the Handoff Desk under the One-shot filter, and the handoff.requested webhook fires with the run_id — use it to follow up through your own channel.
Handed-off runs are not billed.

Errors to handle

Status and code	When
`409 agent_not_ready`	The agent can’t answer yet (for example no model key). Check `readiness.blockers`.
`413 input_too_large`	The input is too long.
`422 variable_missing`, `variable_unknown`	Variables don’t match the agent’s declarations.
`429 quota_exceeded`	The Free plan’s monthly AI conversations are used up (`x-should-retry: false`).
`429 cost_cap_exceeded`	The organization’s daily cost cap was reached.

Billing

A one-shot ask costs 0.25 × the model weight for each started block of 50,000 input tokens — for a typical question, 0.25 of an AI conversation. See Usage and billing.