Skip to main content
Managed AgentsVersion: 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.

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your access token.

Scope:managed-agents.write
Auth methods:OAuthPrivate Integration
Token type:Sub-Account Token

Request​

Headers

Versionstringrequired

API version.

Available optionsv3
Example:v3
Idempotency-Keystringrequired

Unique key for this logical turn. Maximum 128 characters.

Possible values: non-empty and <= 128 characters

Example:turn-7f3cf4c0-39eb-46be-baa3-a1eb15021f25

Path Parameters

managedAgentIdstringrequired

Managed Agent ID.

Example:027ee957-ae94-40ad-89a3-b25c985f729b

Body

locationIdstringrequired

Authorized sub-account ID.

Possible values: non-empty and <= 256 characters

Example:ve9EPM428h8vShlRW1KT
messagestringrequired

User message for this turn.

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

Example:Summarize today's new contacts.
sessionIdstring

Session ID returned by a previous turn.

Possible values: non-empty and <= 256 characters

Example:a1b2c3d4-e5f6-7890-abcd-ef1234567890
contactIdstring

Optional contact to hydrate into runtime context.

Possible values: non-empty and <= 256 characters

Example:cid_abc123def456
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.

Response

Managed Agent turn completed.

successbooleanrequired

Whether the turn completed successfully.

Available optionstrue
Example:true
agentIdstringrequired

Managed Agent that handled the turn.

Example:027ee957-ae94-40ad-89a3-b25c985f729b
sessionIdstringrequired

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

Example:a1b2c3d4-e5f6-7890-abcd-ef1234567890
finalTextstringrequired

Final text returned by the Managed Agent.

Example:Here are today's new contacts…
toolsFiredstring[]required

Tool identifiers invoked during the turn.

Example:["web_search"]
generatedMediaobject[]

Media assets generated during the turn.