Invoke a published agent - Gradient

Invoke runs a published agent version against a single message and returns the agent’s reply. It is the simplest way to call an agent from your own code.

POST https://api.usegradient.dev/v1/agents/<agent-uuid>/versions/<n>/invoke

The call is stateless and starts from an empty transcript. The engine drives the graph, following any agent_swap handoffs and resolving tool calls, until the turn settles, then returns the final assistant text. For a multi-turn conversation where you keep and replay the transcript yourself, use Turn instead.

Path parameters

Segment	Description
`<agent-uuid>`	The agent’s UUID. This is the agent id, not its display name, so agents can safely share names. Find it in the console or via the MCP `list_agents` tool.
`<n>`	A published version, a positive integer such as `1` or `2`. The mutable `draft` is rejected here; publish first.

Request

Header: Authorization: Bearer $GRADIENT_API_KEY. The key needs the agents:invoke scope. See Authentication.
Header: content-type: text/plain.
Body: the user’s message as plain UTF-8 text, up to 1 MB. It must not be empty.

curl -X POST \
  https://api.usegradient.dev/v1/agents/<agent-uuid>/versions/1/invoke \
  -H "authorization: Bearer $GRADIENT_API_KEY" \
  -H "content-type: text/plain" \
  --data-raw 'I need to book a follow-up visit'

{
  "output": "Happy to help you book a follow-up. Can I get your date of birth to find your record?"
}

Response

On success the engine returns 200 with a single field:

Field	Type	Description
`output`	string	The agent’s assistant reply for this message.

Errors

Status	Meaning
`400`	The agent id is not a UUID, the version is not a published positive integer, or the body is empty, too large, or not UTF-8
`401`	Missing or invalid key, or the key lacks `agents:invoke`
`404`	No such agent or version for this organization
`402`	Billing blocks the request (for example, an exhausted trial)

Every invoke is recorded as a production trace, so calls made this way show up alongside chat and voice conversations in the console.