Skip to main content
Version: v3New

Execute a published Managed Agent

POST 
/agent-studio/managed-agents/:managedAgentId/execute

Runs one JSON turn against the published production snapshot. Omit sessionId on the first turn and pass the returned sessionId on subsequent turns. Reuse the same Idempotency-Key only when retrying the exact same logical turn. For a 429 response, retry that key only when retryable is true and Retry-After is present.

Request​

Version stringrequired

API version.

Available optionsv3
Idempotency-Key stringrequired

Unique key for this logical turn. Maximum 128 characters.

Possible values: non-empty and <= 128 characters

managedAgentId stringrequired

Managed Agent ID.

application/json

Bodyrequired

    locationIdstringrequired

    Authorized sub-account ID.

    Possible values: non-empty and <= 256 characters

    messagestringrequired

    User message for this turn.

    Possible values: non-empty and <= 10000 characters, Value must match regular expression \S

    sessionIdstring

    Session ID returned by a previous turn.

    Possible values: non-empty and <= 256 characters

    contactIdstring

    Optional contact to hydrate into runtime context.

    Possible values: non-empty and <= 256 characters

    extraVariablesobject

    Optional JSON variables. Maximum encoded size is 32 KiB and maximum nesting depth is 5. Runtime identity names are reserved and rejected with 400: the roots account, contact and location, and the keys agentId, agencyId, companyId, contactId, executionId, locationId, sessionId and userId. Matching is case-insensitive and applies at the top level and under the optional global, inputs, raw and runtime prefixes, in either dotted (runtime.contact.id) or nested form. Use the endpoint locationId and the top-level contactId instead. These names nested under one of your own keys (for example customer.contactId) are accepted.

application/json

Managed Agent turn completed.

Schema
    successbooleanrequired

    Whether the turn completed successfully.

    Available optionstrue
    agentIdstringrequired

    Managed Agent that handled the turn.

    sessionIdstringrequired

    Pass this value on the next turn to continue the conversation.

    finalTextstringrequired

    Final text returned by the Managed Agent.

    toolsFiredstring[]required

    Tool identifiers invoked during the turn.

    generatedMediaobject[]

    Media assets generated during the turn.