Execute Agent

Executes the specified agent and returns a non-streaming JSON response with the complete agent output. The agent must be in active status and belong to the specified account. locationId is required in the request body. Session Management:

For the first message in a new session, do not include the executionId in the request payload.
The API will return an executionId along with the agent response, which uniquely identifies this conversation session.
To continue the conversation within the same session, include the executionId from the previous response in subsequent requests. This allows the agent to maintain conversation context and history across multiple interactions.

POST https://services.leadconnectorhq.com/agent-studio/agent/{agentId}/execute

Autorización

string

required

Bearer token generado desde el portal Leadway. Ver Autenticación.

string

default:"2021-07-28"

required

Versión de la API.

Path parameters

string

default:"p1q2r3s4t5u6v7w8x9y0z1a2"

required

Query parameters

string

default:"api"

Body

string

default:"How can you help me with my marketing?"

required

Message to send to the agent

string

default:"a1b2c3d4e5f6g7h8i9j0k1l2"

Unique session identifier that maintains conversational context across multiple interactions within the same agent session. Omit this field for the first message in a new session. Include the executionId returned from the previous response to maintain context in subsequent messages.

object

Input variables to pass to the agent. These should match the input variables defined in the agent configuration.

string

default:"b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d"

Published version ID to execute. If not provided, the latest published production version will be used.

object[]

Attachments for the message

Show cada item

string

default:"image"

required

Type of attachment

string

default:"https://example.com/image.png"

required

URL of the image attachment

string

default:"C2QujeCh8ZnC7al2InWR"

required

Account ID

string

default:"cid_abc123def456"

Contact ID to associate with this execution. When provided, contact data will be hydrated and made available to the agent.

Respuestas

200 - Agent executed successfully

boolean

default:"True"

required

Success status

string

default:"a1b2c3d4e5f6g7h8i9j0k1l2"

required

Unique session identifier that maintains conversational context across multiple interactions within the same agent session. Use this ID in subsequent requests to continue the conversation.

string

default:"m9n8o7p6q5r4s3t2u1v0w9x8"

required

Unique identifier for a single interaction cycle, consisting of one user input and the corresponding agent response. Each message exchange generates a new interactionId.

string

default:"I can help you with various tasks..."

required

Agent response text

string

default:"text"

required

Response type

string

default:"text"

required

Expected input type for next interaction

boolean

default:"False"

required

When end node is added in the graph, this will be true if the agent reached the end node in the graph

string

default:"completed"

required

Execution status

boolean

default:"False"

required

Whether flow was switched

object[]

required

Response attachments

object[]

required

Generated outputs

{
  "success": true,
  "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2",
  "interactionId": "m9n8o7p6q5r4s3t2u1v0w9x8",
  "response": "I can help you with various tasks...",
  "type": "text",
  "nextExpectedInput": "text",
  "goalCompletion": false,
  "executionStatus": "completed",
  "flowSwitch": false,
  "attachments": [],
  "generativeOutputs": []
}

400 - Agent is not active or invalid request - locationId is required

401 - Unauthorized

{}

403 - User does not have required scopes to execute this agent

404 - Agent not found

422 - Unprocessable Entity

{}

500 - Internal Server Error

number

default:"500"

string

default:"Internal Server Error"

{
  "statusCode": 500,
  "message": "Internal Server Error"
}

Ejemplo

curl -X POST 'https://services.leadconnectorhq.com/agent-studio/agent/YOUR_agentId/execute' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Version: 2021-07-28' \
  -H 'Content-Type: application/json' \
  -d '{
  "message": "How can you help me with my marketing?",
  "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2",
  "inputVariables": {
    "customerName": "John Doe",
    "orderNumber": "ORD-12345"
  },
  "versionId": "b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "attachments": [
    {
      "type": "image",
      "imageUrl": "https://example.com/image.png"
    }
  ],
  "locationId": "C2QujeCh8ZnC7al2InWR",
  "contactId": "cid_abc123def456"
}'

const response = await fetch('https://services.leadconnectorhq.com/agent-studio/agent/YOUR_agentId/execute', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LEADWAY_TOKEN}`,
    Version: '2021-07-28',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"message": "How can you help me with my marketing?", "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2", "inputVariables": {"customerName": "John Doe", "orderNumber": "ORD-12345"}, "versionId": "b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d", "attachments": [{"type": "image", "imageUrl": "https://example.com/image.png"}], "locationId": "C2QujeCh8ZnC7al2InWR", "contactId": "cid_abc123def456"}),
});
const data = await response.json();

import os, requests
response = requests.request(
    'POST',
    'https://services.leadconnectorhq.com/agent-studio/agent/YOUR_agentId/execute',
    headers={
        'Authorization': f"Bearer {os.environ['LEADWAY_TOKEN']}",
        'Version': '2021-07-28',
        'Content-Type': 'application/json',
    },
    json={"message": "How can you help me with my marketing?", "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2", "inputVariables": {"customerName": "John Doe", "orderNumber": "ORD-12345"}, "versionId": "b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d", "attachments": [{"type": "image", "imageUrl": "https://example.com/image.png"}], "locationId": "C2QujeCh8ZnC7al2InWR", "contactId": "cid_abc123def456"},
)
data = response.json()

<?php
$ch = curl_init('https://services.leadconnectorhq.com/agent-studio/agent/YOUR_agentId/execute');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('LEADWAY_TOKEN'),
        'Version: 2021-07-28',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode({'message': 'How can you help me with my marketing?', 'executionId': 'a1b2c3d4e5f6g7h8i9j0k1l2', 'inputVariables': {'customerName': 'John Doe', 'orderNumber': 'ORD-12345'}, 'versionId': 'b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d', 'attachments': [{'type': 'image', 'imageUrl': 'https://example.com/image.png'}], 'locationId': 'C2QujeCh8ZnC7al2InWR', 'contactId': 'cid_abc123def456'}),
]);
$data = json_decode(curl_exec($ch), true);

Empezar

Scopes

Autorización

Path parameters

Query parameters

Body

Respuestas

Ejemplo

​Autorización

​Path parameters

​Query parameters

​Body

​Respuestas

​Ejemplo

Autorización

Path parameters

Query parameters

Body

Respuestas

Ejemplo