Agent

Invoke one agent tool directly

Run ONE named tool directly, with no model in the loop: the caller supplies the arguments the agent would otherwise choose. This is the seam for building your own agent on top of Talonic's retrieval and provenance while driving control flow yourself.

The same capability matrix the agent loop applies governs this route, so a key can only run the tools whose can_invoke is true on GET /v1/agent/tools; a denied tool answers 403 naming the capability it needs. scope and on_behalf_of behave exactly as on POST /v1/ask: the scope is a bound SQL predicate, and on_behalf_of applies that user's compartment visibility.

Direct invocation charges no credits: every tool this key can reach does no model work, so there is no model call to meter. The route is bounded by the agent_tools rate-limit namespace instead. A tool that runs but fails answers 422 with the tool's own failure summary.

post/v1/agent/tools/{name}/invoke

Request

  • Base URL: https://api.talonic.com
  • URL: https://api.talonic.com/v1/agent/tools/{name}/invoke
  • Auth: HTTP bearer

Path parameters

namestring required

The tool name as listed by GET /v1/agent/tools.

Request body

argsobject

Arguments matching the tool's input_schema from GET /v1/agent/tools.

scopeobject

Restrict the invocation to a slice of the workspace, exactly as on POST /v1/ask.

on_behalf_ofstring uuid

Apply this workspace user's compartment visibility to the invocation.

Response

The tool ran; its raw output plus any cards, artifacts, and citations.

toolstring
okboolean
contentstring

The tool's raw output, usually JSON serialized as a string.

cardsobject[]
artifactsobject[]

Changes

No recorded changes to this operation across all 1 revision of this API.