WorkOS PHP SDK

Agents
in package

Application

Properties

$client : HttpClient

Methods

__construct() : mixed
createBlueprint() : AgentBlueprint: Create an agent blueprint
createBlueprintToken() : AgentToken: Mint an agent token
createValidate() : AgentCredentialValidation: Validate an agent credential
deleteBlueprint() : void: Delete an agent blueprint
deleteInstance() : void: Delete an agent instance
getBlueprint() : AgentBlueprint: Get an agent blueprint
getInstance() : AgentInstance: Get an agent instance
getRegistration() : AgentRegistration: Get an agent registration
getSession() : AgentInstanceSession: Get an agent instance session
listBlueprints() : PaginatedResponse<string|int, AgentBlueprint>: List agent blueprints
listInstances() : PaginatedResponse<string|int, AgentInstance>: List agent instances
listSessions() : PaginatedResponse<string|int, AgentInstanceSession>: List agent instance sessions
revokeRegistration() : AgentRegistration: Revoke an agent registration
revokeSession() : AgentInstanceSession: Revoke an agent instance session
updateAttempts() : ClaimViewResponse: Link a claim attempt to an external user
updateBlueprint() : AgentBlueprint: Update an agent blueprint
validateBlueprintToken() : AgentTokenValidation: Validate an agent token

$client read-only


        private
            HttpClient
    $client

__construct()


    public
                    __construct(HttpClient $client) : mixed

Parameters

$client : HttpClient

createBlueprint()

Create an agent blueprint


    public
                    createBlueprint(string $name[, string|null $description = null ][, array<string|int, string>|null $permissions = null ][, AgentBlueprintsCreateRequestInvocableBy|null $invocableBy = null ][, AgentBlueprintsCreateRequestInvocableAs|null $invocableAs = null ][, AgentBlueprintsCreateRequestSessionSetting|null $sessionSettings = null ][, RequestOptions|null $options = null ]) : AgentBlueprint

Creates an agent blueprint: the template describing what an agent may do (its permission ceiling), who may invoke it, and the lifetimes of its sessions.

Parameters

$name : string: Human-readable name of the agent blueprint.
$description : string|null = null: Human-readable description of the agent blueprint.
$permissions : array<string|int, string>|null = null: Permission slugs forming the ceiling on what sessions minted from this blueprint may do. Each slug must exist in the environment.
$invocableBy : AgentBlueprintsCreateRequestInvocableBy|null = null: Who may mint sessions from this blueprint.
$invocableAs : AgentBlueprintsCreateRequestInvocableAs|null = null: How sessions may be minted from this blueprint.
$sessionSettings : AgentBlueprintsCreateRequestSessionSetting|null = null: Token and session lifetimes for sessions minted from this blueprint.
$options : RequestOptions|null = null

Return values

AgentBlueprint

createBlueprintToken()

Mint an agent token


    public
                    createBlueprintToken(string $agentBlueprintId, AgentBlueprintsTokenMintTokenRequestType $type[, string|null $userAccessToken = null ][, string|null $intent = null ][, string|null $organizationId = null ][, string|null $agentAccessToken = null ][, string|null $refreshToken = null ][, RequestOptions|null $options = null ]) : AgentToken

Mint an agent access token (and backing session) from an agent blueprint. The session can be user-delegated (exchanging a user access token), autonomous (the agent acting as itself in an organization), agent-delegated (the agent exchanging its own access token for a new session on the same instance), or a refresh of a previously issued refresh token.

Parameters

$agentBlueprintId : string: The unique ID of the agent blueprint.
$type : AgentBlueprintsTokenMintTokenRequestType: How the session is minted: user_delegated, autonomous, agent_delegated, or refresh.
$userAccessToken : string|null = null: The access token of the user delegating to the agent. The token identifies the user and organization; effective permissions are resolved server-side.
$intent : string|null = null: Optional caller-supplied context, echoed as an object with a text field in the intent claim of the minted access token.
$organizationId : string|null = null: The organization the agent acts within when operating as itself.
$agentAccessToken : string|null = null: The agent's own access token to exchange for a new session on the same instance. The token must have been minted from this blueprint; permissions are re-derived from current authority.
$refreshToken : string|null = null: The refresh token issued with a previous agent access token. Refresh tokens are single-use: each refresh rotates it.
$options : RequestOptions|null = null

Return values

AgentToken

createValidate()

Validate an agent credential


    public
                    createValidate(AgentAdminValidateCredentialRequestType $type, string $credential[, string|null $audience = null ][, RequestOptions|null $options = null ]) : AgentCredentialValidation

Validate an agent credential — an API key or access token — against the environment of the API key used to authenticate the request. This is a read-only check: it never consumes or mutates the credential.

Parameters

$type : AgentAdminValidateCredentialRequestType: The kind of credential being validated — an agent API key or an agent access token.
$credential : string: The credential value to validate: the API key value for api_key, or the access token (JWT) for access_token.
$audience : string|null = null: When provided, the access token's aud claim is verified against this value. Tokens issued for a different resource are rejected.
$options : RequestOptions|null = null

Return values

AgentCredentialValidation

deleteBlueprint()

Delete an agent blueprint


    public
                    deleteBlueprint(string $agentBlueprintId[, RequestOptions|null $options = null ]) : void

Deletes an agent blueprint along with its configuration, instances, and sessions.

Parameters

$agentBlueprintId : string: The unique ID of the agent blueprint.
$options : RequestOptions|null = null

deleteInstance()

Delete an agent instance


    public
                    deleteInstance(string $agentInstanceId[, RequestOptions|null $options = null ]) : void

Deletes an agent instance along with its sessions, invalidating their refresh tokens.

Parameters

$agentInstanceId : string: The unique ID of the agent instance.
$options : RequestOptions|null = null

getBlueprint()

Get an agent blueprint


    public
                    getBlueprint(string $agentBlueprintId[, RequestOptions|null $options = null ]) : AgentBlueprint

Retrieves an agent blueprint by ID.

Parameters

$agentBlueprintId : string: The unique ID of the agent blueprint.
$options : RequestOptions|null = null

Return values

AgentBlueprint

getInstance()

Get an agent instance


    public
                    getInstance(string $agentInstanceId[, RequestOptions|null $options = null ]) : AgentInstance

Retrieves an agent instance by ID.

Parameters

$agentInstanceId : string: The unique ID of the agent instance.
$options : RequestOptions|null = null

Return values

AgentInstance

getRegistration()

Get an agent registration


    public
                    getRegistration(string $id[, RequestOptions|null $options = null ]) : AgentRegistration

Retrieve the details of an agent registration by ID. The registration is scoped to the environment of the API key used to authenticate the request.

Parameters

$id : string: The unique ID of the agent registration.
$options : RequestOptions|null = null

Return values

AgentRegistration

getSession()

Get an agent instance session


    public
                    getSession(string $agentInstanceSessionId[, RequestOptions|null $options = null ]) : AgentInstanceSession

Retrieves an agent instance session by ID.

Parameters

$agentInstanceSessionId : string: The unique ID of the agent instance session.
$options : RequestOptions|null = null

Return values

AgentInstanceSession

listBlueprints()

List agent blueprints


    public
                    listBlueprints([string|null $before = null ][, string|null $after = null ][, int|null $limit = null ][, PaginationOrder $order = PaginationOrder::Desc ][, RequestOptions|null $options = null ]) : PaginatedResponse<string|int, AgentBlueprint>

Lists the agent blueprints in the current environment.

Parameters

$before : string|null = null: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with "obj_123", your subsequent call can include before="obj_123" to fetch a new batch of objects before "obj_123".
$after : string|null = null: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with "obj_123", your subsequent call can include after="obj_123" to fetch a new batch of objects after "obj_123".
$limit : int|null = null: Upper limit on the number of objects to return, between 1 and 100. Defaults to 10.
$order : PaginationOrder = PaginationOrder::Desc: Order the results by the creation time. Supported values are "asc" (ascending), "desc" (descending), and "normal" (descending with reversed cursor semantics where before fetches older records and after fetches newer records). Defaults to "desc".
$options : RequestOptions|null = null

Return values

PaginatedResponse<string|int, AgentBlueprint>

listInstances()

List agent instances


    public
                    listInstances([string|null $before = null ][, string|null $after = null ][, int|null $limit = null ][, PaginationOrder $order = PaginationOrder::Desc ][, string|null $organizationId = null ][, string|null $agentBlueprintId = null ][, RequestOptions|null $options = null ]) : PaginatedResponse<string|int, AgentInstance>

Lists the agent instances in the current environment. Instances are created implicitly when tokens are minted.

Parameters

$before : string|null = null: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with "obj_123", your subsequent call can include before="obj_123" to fetch a new batch of objects before "obj_123".
$after : string|null = null: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with "obj_123", your subsequent call can include after="obj_123" to fetch a new batch of objects after "obj_123".
$limit : int|null = null: Upper limit on the number of objects to return, between 1 and 100. Defaults to 10.
$order : PaginationOrder = PaginationOrder::Desc: Order the results by the creation time. Supported values are "asc" (ascending), "desc" (descending), and "normal" (descending with reversed cursor semantics where before fetches older records and after fetches newer records). Defaults to "desc".
$organizationId : string|null = null: Only return instances acting within this organization.
$agentBlueprintId : string|null = null: Only return instances minted from this blueprint.
$options : RequestOptions|null = null

Return values

PaginatedResponse<string|int, AgentInstance>

listSessions()

List agent instance sessions


    public
                    listSessions([string|null $before = null ][, string|null $after = null ][, int|null $limit = null ][, PaginationOrder $order = PaginationOrder::Desc ][, string|null $organizationId = null ][, string|null $agentBlueprintId = null ][, string|null $agentInstanceId = null ][, RequestOptions|null $options = null ]) : PaginatedResponse<string|int, AgentInstanceSession>

Lists the agent instance sessions in the current environment. Sessions are created when tokens are minted.

Parameters

$before : string|null = null: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with "obj_123", your subsequent call can include before="obj_123" to fetch a new batch of objects before "obj_123".
$after : string|null = null: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with "obj_123", your subsequent call can include after="obj_123" to fetch a new batch of objects after "obj_123".
$limit : int|null = null: Upper limit on the number of objects to return, between 1 and 100. Defaults to 10.
$order : PaginationOrder = PaginationOrder::Desc: Order the results by the creation time. Supported values are "asc" (ascending), "desc" (descending), and "normal" (descending with reversed cursor semantics where before fetches older records and after fetches newer records). Defaults to "desc".
$organizationId : string|null = null: Only return sessions of instances acting within this organization.
$agentBlueprintId : string|null = null: Only return sessions of instances minted from this blueprint.
$agentInstanceId : string|null = null: Only return sessions belonging to this agent instance.
$options : RequestOptions|null = null

Return values

PaginatedResponse<string|int, AgentInstanceSession>

revokeRegistration()

Revoke an agent registration


    public
                    revokeRegistration(string $id[, RequestOptions|null $options = null ]) : AgentRegistration

Revoke an agent registration by ID. Revocation is permanent: the registration, its identity assertions, and every access token or API key issued from it stop working, and the agent must register again. Revoking an already revoked registration succeeds and returns the original revoked_at. The registration is scoped to the environment of the API key used to authenticate the request.

Parameters

$id : string: The unique ID of the agent registration.
$options : RequestOptions|null = null

Return values

AgentRegistration

revokeSession()

Revoke an agent instance session


    public
                    revokeSession(string $agentInstanceSessionId[, RequestOptions|null $options = null ]) : AgentInstanceSession

Revokes an agent instance session, invalidating its refresh token and every access token minted under it. Revocation is idempotent: revoking an already-revoked session keeps the original revoked_at, and revoking an already-expired session returns the session with status: expired and a null revoked_at.

Parameters

$agentInstanceSessionId : string: The unique ID of the agent instance session.
$options : RequestOptions|null = null

Return values

AgentInstanceSession

updateAttempts()

Link a claim attempt to an external user


    public
                    updateAttempts(string $type, string $claimAttemptToken, AgentAdminLinkClaimAttemptToExternalUserRequestUser $user[, string|null $organizationId = null ][, RequestOptions|null $options = null ]) : ClaimViewResponse

Link an external user to a claim attempt and retrieve the code needed for the agent to complete the claim. The user is looked up by external ID; if no user exists, one is created. When the user belongs to multiple organizations, an explicit organization must be provided.

Parameters

$type : string: The operation to perform on the claim attempt. Currently only link_external_user is supported.
$claimAttemptToken : string: The token identifying the claim attempt.
$user : AgentAdminLinkClaimAttemptToExternalUserRequestUser: The user to attach to the claim attempt, identified by email and external ID.
$organizationId : string|null = null: The organization to place the agent in. Required when the user belongs to more than one organization.
$options : RequestOptions|null = null

Return values

ClaimViewResponse

updateBlueprint()

Update an agent blueprint


    public
                    updateBlueprint(string $agentBlueprintId[, string|null $name = null ][, string|null $description = null ][, array<string|int, string>|null $permissions = null ][, AgentBlueprintsUpdateRequestInvocableBy|null $invocableBy = null ][, AgentBlueprintsUpdateRequestInvocableAs|null $invocableAs = null ][, AgentBlueprintsUpdateRequestSessionSetting|null $sessionSettings = null ][, RequestOptions|null $options = null ]) : AgentBlueprint

Updates an agent blueprint. Omitted fields are left unchanged; provided lists replace the existing configuration.

Parameters

$agentBlueprintId : string: The unique ID of the agent blueprint.
$name : string|null = null: Human-readable name of the agent blueprint.
$description : string|null = null: Human-readable description of the agent blueprint. Pass null to clear it.
$permissions : array<string|int, string>|null = null: Permission slugs forming the ceiling on what sessions minted from this blueprint may do. Each slug must exist in the environment.
$invocableBy : AgentBlueprintsUpdateRequestInvocableBy|null = null: Who may mint sessions from this blueprint. Omitted lists are left unchanged.
$invocableAs : AgentBlueprintsUpdateRequestInvocableAs|null = null: How sessions may be minted from this blueprint. Omitted lists are left unchanged.
$sessionSettings : AgentBlueprintsUpdateRequestSessionSetting|null = null: Token and session lifetimes for sessions minted from this blueprint. Omitted fields are left unchanged.
$options : RequestOptions|null = null

Return values

AgentBlueprint

validateBlueprintToken()

Validate an agent token


    public
                    validateBlueprintToken(string $agentBlueprintId, string $agentAccessToken[, RequestOptions|null $options = null ]) : AgentTokenValidation

Validates an agent access token: verifies its signature against the environment, that it was minted under this blueprint, and that the backing session is live (not revoked or expired, and — for delegated sessions — that the delegating user session has not ended). Returns the token claims and session metadata when valid; invalid tokens are reported as errors with stable codes.

Parameters

$agentBlueprintId : string: The unique ID of the agent blueprint.
$agentAccessToken : string: The agent access token (a JWT) to validate.
$options : RequestOptions|null = null

Return values

AgentTokenValidation

Agents in package Application

Table of Contents

Properties

Methods

Properties

$client read-only

Methods

__construct()

Parameters

createBlueprint()

Parameters

Tags

Return values

createBlueprintToken()

Parameters

Tags

Return values

createValidate()

Parameters

Tags

Return values

deleteBlueprint()

Parameters

Tags

deleteInstance()

Parameters

Tags

getBlueprint()

Parameters

Tags

Return values

getInstance()

Parameters

Tags

Return values

getRegistration()

Parameters

Tags

Return values

getSession()

Parameters

Tags

Return values

listBlueprints()

Parameters

Tags

Return values

listInstances()

Parameters

Tags

Return values

listSessions()

Parameters

Tags

Return values

revokeRegistration()

Parameters

Tags

Return values

revokeSession()

Parameters

Tags

Return values

updateAttempts()

Parameters

Tags

Return values

updateBlueprint()

Parameters

Tags

Return values

validateBlueprintToken()

Parameters

Tags

Return values

Agents
in package

Application