execute

Execute Agent

Execute an agent with a message and return the complete response.

This endpoint provides a synchronous (non-streaming) way to run agents, perfect for AI helper features like "Improve with AI" buttons.

The agent can be identified by:

  • Numeric ID: "123"
  • Identifier string: "my-helper-agent"
  • URI format: "agent://my-helper-agent"

Optional features:

  • context: Variables to inject into the message template using {{variable}} syntax
  • response_format: JSON schema to parse structured output from the response

Returns: ExecuteAgentResponse with the agent's complete response and metadata

Raises: 400: User must have an account 404: Agent not found 500: Execution failed

post/api/v1/execute

Request

  • Base URL: https://api.gnosari.com (the document declares no server; this is the origin it was published from)
  • URL: https://api.gnosari.com/api/v1/execute
  • Auth: one of:
    • HTTP bearer
    • API key in header X-AUTH-TOKEN

Request body

agent_refstring required

Agent ID, identifier, or URI (e.g., '123', 'my-agent', 'agent://my-agent')

messagestring required

Message/prompt to send to the agent

response_formatobject nullable

Optional JSON schema for structured output parsing

contextobject nullable

Optional context variables for template rendering (e.g., {{variable}})

Example request

{
  "agent_ref": "instruction-improver",
  "context": {
    "content": "Help users with their questions"
  },
  "message": "Improve the following text:\n\n{{content}}"
}

Response

Successful Response

successboolean required

Whether execution completed successfully

contentstring required

The agent's response content

structured_outputobject nullable

Parsed structured output if response_format was provided

agent_namestring required

Name of the executed agent

agent_idinteger required

ID of the executed agent

execution_time_msinteger required

Execution time in milliseconds

Example response

{
  "agent_id": 42,
  "agent_name": "Instruction Improver",
  "content": "I am a helpful AI assistant that provides clear, accurate answers to user questions.",
  "execution_time_ms": 1250,
  "success": true
}

Changes

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