Agents
60 methods on the Agents resource.
60 methods · 4 available to app tokens36 pages in SDK Reference
import { Compozy } from "@compozy/client";60 of 60
addAgentMemoryadoptAgentInstanceapproveAgentHeartbeatAuthorityapproveAgentHeartbeatScriptapproveAgentSkillReviewarchiveAgentInstancebatchAgentActivitycheckAgentInstancecreateAgentcreateAgentInstancedeleteAgentdeleteAgentHeartbeatdeleteAgentSouldraftAgentInstructionsduplicateAgentensureAgentInstanceMaingetAgentgetAgentActivitygetAgentDefinitionSoulgetAgentHeartbeatgetAgentHeartbeatAuthoritygetAgentHeartbeatSourcesgetAgentHeartbeatStatusgetAgentInstancegetAgentInstanceAwaygetAgentInstanceOccurrencegetAgentMemorygetAgentSkillReviewlistAgentCataloglistAgentHeartbeatHistorylistAgentInstanceCheckInslistAgentInstanceReportslistAgentInstanceslistAgentMemoryHistorylistAgentSkillReviewslistAgentSoulHistorylistAgentslistAgentsAggregatemarkAgentInstanceSeenpauseAgentInstancepickAgentInstanceProposalputAgentHeartbeatputAgentMemoryputAgentSoulrejectAgentSkillReviewremoveAgentMemoryreplaceAgentMemoryresumeAgentInstancerevokeAgentHeartbeatAuthorityrevokeAgentHeartbeatScriptrollbackAgentHeartbeatrollbackAgentMemoryrollbackAgentSoulsearchAgentMemoryupdateAgentupdateAgentInstancevalidateAgentDefinitionSoulvalidateAgentHeartbeatvalidateAgentMemorywakeAgentHeartbeat
addAgentMemory
Add a dated memory entry (experimental)
compozy.agents.addAgentMemory({ path, query, body }) → Promise<AgentMemoryDocument>
Options
- namestringpathrequired
- Agent name
- workspacestringquery
- Workspace selecting the agent definition
- profilestringquery
- Act as this profile by name
Request bodyAgentMemoryAddRequest
POST /api/agents/{name}/memory/entriesapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.addAgentMemory({ path: { "name": "name" }, body: { /* request fields */ } });adoptAgentInstance
Adopt a root session as an instance
compozy.agents.adoptAgentInstance({ query, body }) → Promise<AgentInstanceResponse>
Options
- profilestringquery
- Act as this profile by name
Request bodyAgentInstanceAdoptRequest
POST /api/agent-instances/adoptapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.adoptAgentInstance({ body: { /* request fields */ } });approveAgentHeartbeatAuthority
approve check-in authority
compozy.agents.approveAgentHeartbeatAuthority({ path, query, body }) → Promise<void>
Options
- namestringpathrequired
- Agent name
- workspace_idstringquery
- Workspace id
- profilestringquery
- Act as this profile by name
Request bodyHeartbeatScriptApprovalRequest
POST /api/agents/{name}/heartbeat/authority/approveapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.approveAgentHeartbeatAuthority({ path: { "name": "name" }, body: { /* request fields */ } });approveAgentHeartbeatScript
Approve exact source script bytes (operator only)
compozy.agents.approveAgentHeartbeatScript({ path, query, body }) → Promise<HeartbeatScriptApprovalPayload>
Options
- namestringpathrequired
- Agent name
- scriptstringpathrequired
- Script name
- workspace_idstringquery
- Workspace id
- profilestringquery
- Act as this profile by name
Request bodyHeartbeatScriptApprovalRequest
POST /api/agents/{name}/heartbeat/scripts/{script}/approveapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.approveAgentHeartbeatScript({ path: { "name": "name", "script": "script" }, body: { /* request fields */ } });approveAgentSkillReview
Decide a skill review as the operator (experimental)
compozy.agents.approveAgentSkillReview({ path, query, body }) → Promise<AgentSkillReviewResponse>
Options
- idstringpathrequired
- Review ID
- profilestringquery
- Act as this profile by name
Request bodyAgentSkillReviewDecisionRequest
POST /api/agent-skill-reviews/{id}/approveapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.approveAgentSkillReview({ path: { "id": "id" }, body: { /* request fields */ } });archiveAgentInstance
Archive an agent instance
compozy.agents.archiveAgentInstance({ path, query }) → Promise<void>
Options
- idstringpathrequired
- Instance ID
- profilestringquery
- Act as this profile by name
DELETE /api/agent-instances/{id}app tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.archiveAgentInstance({ path: { "id": "id" } });batchAgentActivity
Read activity for up to 100 agent and workspace selections in request order
compozy.agents.batchAgentActivity({ query, body }) → Promise<AgentActivityBatchResponse>
Options
- profilestringquery
- Act as this profile by name
Request bodyAgentActivityBatchRequest
POST /api/agents/activityapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.batchAgentActivity({ body: { /* request fields */ } });checkAgentInstance
Check an agent instance
compozy.agents.checkAgentInstance({ path, query, body }) → Promise<CheckAgentInstanceResponse>
Options
- idstringpathrequired
- Instance ID
- profilestringquery
- Act as this profile by name
Request bodyAgentInstanceCheckRequest
POST /api/agent-instances/{id}/checkapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.checkAgentInstance({ path: { "id": "id" }, body: { /* request fields */ } });createAgent
Create a global or workspace-local AGENT.md definition
compozy.agents.createAgent({ query, body }) → Promise<AgentResponse>
Options
- profilestringquery
- Act as this profile by name
Request bodyCreateAgentRequestWritable
POST /api/agentsapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.createAgent({ body: { /* request fields */ } });createAgentInstance
Create an always-on agent instance
compozy.agents.createAgentInstance({ query, body }) → Promise<CreateAgentInstanceResponse>
Options
- profilestringquery
- Act as this profile by name
Request bodyAgentInstanceCreateRequest
POST /api/agent-instancesapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.createAgentInstance({ body: { /* request fields */ } });Show all 60 methods
deleteAgent
Durably delete one effective authored agent definition
compozy.agents.deleteAgent({ path, query }) → Promise<DeleteAgentResponse>
Options
- namestringpathrequired
- Agent name
- workspacestringquery
- Workspace id, name, or path used to resolve the effective definition
- profilestringquery
- Act as this profile by name
DELETE /api/agents/{name}app tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.deleteAgent({ path: { "name": "name" } });deleteAgentHeartbeat
Delete HEARTBEAT.md through managed authoring
compozy.agents.deleteAgentHeartbeat({ path, query, body }) → Promise<HeartbeatMutationResponse>
Options
- namestringpathrequired
- Agent name
- profilestringquery
- Act as this profile by name
Request bodyHeartbeatDeleteByPathRequest
DELETE /api/agents/{name}/heartbeatapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.deleteAgentHeartbeat({ path: { "name": "name" }, body: { /* request fields */ } });deleteAgentSoul
Delete SOUL.md through managed authoring
compozy.agents.deleteAgentSoul({ path, query, body }) → Promise<AgentSoulMutationResponse>
Options
- namestringpathrequired
- Agent name
- profilestringquery
- Act as this profile by name
Request bodyAgentSoulDeleteByPathRequest
DELETE /api/agents/{name}/soulapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.deleteAgentSoul({ path: { "name": "name" }, body: { /* request fields */ } });draftAgentInstructions
Draft agent instructions without saving a definition
compozy.agents.draftAgentInstructions({ query, body }) → Promise<DraftAgentInstructionsResponse>
Options
- profilestringquery
- Act as this profile by name
Request bodyDraftAgentInstructionsRequest
POST /api/agents/draft-instructionsapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.draftAgentInstructions({ body: { /* request fields */ } });duplicateAgent
Duplicate one effective authored agent definition server-side
compozy.agents.duplicateAgent({ path, query, body }) → Promise<AgentResponse>
Options
- namestringpathrequired
- Source agent name
- profilestringquery
- Act as this profile by name
Request bodyDuplicateAgentRequest
POST /api/agents/{name}/duplicateapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.duplicateAgent({ path: { "name": "name" }, body: { /* request fields */ } });ensureAgentInstanceMain
Ensure the main session exists
compozy.agents.ensureAgentInstanceMain({ path, query }) → Promise<AgentInstanceResponse>
Options
- idstringpathrequired
- Instance ID
- profilestringquery
- Act as this profile by name
POST /api/agent-instances/{id}/ensure-mainapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.ensureAgentInstanceMain({ path: { "id": "id" } });getAgent
Get one agent definition by name, optionally resolved for a workspace
compozy.agents.getAgent({ path, query }) → Promise<AgentResponse>
Options
- namestringpathrequired
- Agent name
- workspacestringquery
- Workspace id, name, or path used to resolve a workspace-local agent
- profilestringquery
- Act as this profile by name
GET /api/agents/{name}app tokens allowed
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.getAgent({ path: { "name": "name" } });getAgentActivity
Read agent activity across authorized workspaces
compozy.agents.getAgentActivity({ path, query }) → Promise<AgentActivityResponse>
Options
- namestringpathrequired
- Agent name
- daysintegerquery
- Number of days, from 1 to 365; defaults to 30
- profilestringquery
- Act as this profile by name
GET /api/agents/{name}/activityapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.getAgentActivity({ path: { "name": "name" } });getAgentDefinitionSoul
Inspect the resolved Soul read model for an agent definition
compozy.agents.getAgentDefinitionSoul({ path, query }) → Promise<AgentSoulPayload>
Options
- namestringpathrequired
- Agent name
- workspace_idstringquery
- Workspace id
- profilestringquery
- Act as this profile by name
GET /api/agents/{name}/soulapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.getAgentDefinitionSoul({ path: { "name": "name" } });getAgentHeartbeat
Inspect the resolved Heartbeat policy for an agent definition
compozy.agents.getAgentHeartbeat({ path, query }) → Promise<HeartbeatPolicyPayload>
Options
- namestringpathrequired
- Agent name
- workspace_idstringquery
- Workspace id
- profilestringquery
- Act as this profile by name
GET /api/agents/{name}/heartbeatapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.getAgentHeartbeat({ path: { "name": "name" } });getAgentHeartbeatAuthority
show check-in authority
compozy.agents.getAgentHeartbeatAuthority({ path, query }) → Promise<HeartbeatAuthorityPayload>
Options
- namestringpathrequired
- Agent name
- workspace_idstringquery
- Workspace id
- profilestringquery
- Act as this profile by name
GET /api/agents/{name}/heartbeat/authorityapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.getAgentHeartbeatAuthority({ path: { "name": "name" } });getAgentHeartbeatSources
List check-in source kinds, scripts and effective limits
compozy.agents.getAgentHeartbeatSources({ path, query }) → Promise<HeartbeatSourceCatalogPayload>
Options
- namestringpathrequired
- Agent name
- workspace_idstringquery
- Workspace id
- profilestringquery
- Act as this profile by name
GET /api/agents/{name}/heartbeat/sourcesapp tokens allowed
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.getAgentHeartbeatSources({ path: { "name": "name" } });getAgentHeartbeatStatus
Read Heartbeat policy status, wake state, and optional session health
compozy.agents.getAgentHeartbeatStatus({ path, query }) → Promise<HeartbeatStatusResponse>
Options
- namestringpathrequired
- Agent name
- workspace_idstringquery
- Workspace id
- session_idstringquery
- Session id for wake state and health
- include_session_healthbooleanquery
- Include session health when a session id is supplied
- include_recent_wake_eventsbooleanquery
- Include recent wake audit rows
- profilestringquery
- Act as this profile by name
GET /api/agents/{name}/heartbeat/statusapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.getAgentHeartbeatStatus({ path: { "name": "name" } });getAgentInstance
Get an agent instance
compozy.agents.getAgentInstance({ path, query }) → Promise<AgentInstanceResponse>
Options
- idstringpathrequired
- Instance ID
- profilestringquery
- Read one profile's rows by name
- all_profilesbooleanquery
- Read the owner-labeled all-profiles aggregate
GET /api/agent-instances/{id}app tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.getAgentInstance({ path: { "id": "id" } });getAgentInstanceAway
Read the operator's instance away digest
compozy.agents.getAgentInstanceAway({ path, query }) → Promise<AgentInstanceAwayResponse>
Options
- idstringpathrequired
- Instance ID
- profilestringquery
- Read one profile's rows by name
- all_profilesbooleanquery
- Read the owner-labeled all-profiles aggregate
GET /api/agent-instances/{id}/awayapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.getAgentInstanceAway({ path: { "id": "id" } });getAgentInstanceOccurrence
Read an instance check occurrence
compozy.agents.getAgentInstanceOccurrence({ path, query }) → Promise<AgentInstanceOccurrenceResponse>
Options
- idstringpathrequired
- Instance ID
- occurrencestringpathrequired
- Occurrence ID
- profilestringquery
- Read one profile's rows by name
- all_profilesbooleanquery
- Read the owner-labeled all-profiles aggregate
GET /api/agent-instances/{id}/occurrences/{occurrence}app tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.getAgentInstanceOccurrence({ path: { "id": "id", "occurrence": "occurrence" } });getAgentMemory
Inspect agent memory (experimental)
compozy.agents.getAgentMemory({ path, query }) → Promise<AgentMemoryDocument>
Options
- namestringpathrequired
- Agent name
- workspacestringquery
- Workspace selecting the agent definition
- profilestringquery
- Act as this profile by name
GET /api/agents/{name}/memoryapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.getAgentMemory({ path: { "name": "name" } });getAgentSkillReview
Read exact proposed skill contents (experimental)
compozy.agents.getAgentSkillReview({ path, query }) → Promise<AgentSkillReviewResponse>
Options
- idstringpathrequired
- Review ID
- profilestringquery
- Act as this profile by name
GET /api/agent-skill-reviews/{id}app tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.getAgentSkillReview({ path: { "id": "id" } });listAgentCatalog
List a filtered agent fleet with exact session metrics
compozy.agents.listAgentCatalog({ query }) → Promise<AgentCatalogResponse>
Options
- workspacestringquery
- Workspace id, name, or path; omit for Global definitions and cross-workspace session metrics
- group"agent"query
- Group identical scoped definitions
- namestringquery
- Exact agent name
- qstringquery
- Case-insensitive agent name, label or category search
- categorystringquery
- Exact category path joined by slash separators
- status"active" | "idle"query
- Agent session status
- cursorstringquery
- Opaque cursor bound to workspace and filters
- limitintegerquery
- Agents per page (1-100; default 50)
- profilestringquery
- Act as this profile by name
GET /api/agents/catalogapp tokens allowed
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.listAgentCatalog({ query: { "status": "active" } });listAgentHeartbeatHistory
List managed HEARTBEAT.md authoring revisions
compozy.agents.listAgentHeartbeatHistory({ path, query }) → Promise<HeartbeatHistoryResponse>
Options
- namestringpathrequired
- Agent name
- workspace_idstringquery
- Workspace id
- limitintegerquery
- Maximum number of revisions to return
- cursorstringquery
- Revision cursor
- profilestringquery
- Act as this profile by name
GET /api/agents/{name}/heartbeat/historyapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.listAgentHeartbeatHistory({ path: { "name": "name" } });listAgentInstanceCheckIns
List instance wake events
compozy.agents.listAgentInstanceCheckIns({ path, query }) → Promise<AgentInstanceCheckInsResponse>
Options
- idstringpathrequired
- Instance ID
- cursorstringquery
- Pagination cursor
- limitintegerquery
- Page size from 1 to 100; defaults to 50
- profilestringquery
- Read one profile's rows by name
- all_profilesbooleanquery
- Read the owner-labeled all-profiles aggregate
GET /api/agent-instances/{id}/check-insapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.listAgentInstanceCheckIns({ path: { "id": "id" } });listAgentInstanceReports
List durable instance reports
compozy.agents.listAgentInstanceReports({ path, query }) → Promise<AgentInstanceReportsResponse>
Options
- idstringpathrequired
- Instance ID
- statestringquery
- Filter by pending, reserved, delivered, or indeterminate
- cursorstringquery
- Pagination cursor
- limitstringquery
- Page size
- profilestringquery
- Read one profile's rows by name
- all_profilesbooleanquery
- Read the owner-labeled all-profiles aggregate
GET /api/agent-instances/{id}/reportsapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.listAgentInstanceReports({ path: { "id": "id" } });listAgentInstances
List agent instances
compozy.agents.listAgentInstances({ query }) → Promise<AgentInstanceListResponse>
Options
- workspacestringquery
- Workspace reference
- all_workspacesstringquery
- Include all workspaces
- peersstringquery
- Read reachable peers without private instance details
- agentstringquery
- Agent name
- statestringquery
- Instance state
- cursorstringquery
- Pagination cursor
- limitstringquery
- Page size
- profilestringquery
- Read one profile's rows by name
- all_profilesbooleanquery
- Read the owner-labeled all-profiles aggregate
GET /api/agent-instancesapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.listAgentInstances();listAgentMemoryHistory
List the last fifty memory revisions (experimental)
compozy.agents.listAgentMemoryHistory({ path, query }) → Promise<AgentMemoryHistoryResponse>
Options
- namestringpathrequired
- Agent name
- workspacestringquery
- Workspace selecting the agent definition
- profilestringquery
- Act as this profile by name
GET /api/agents/{name}/memory/historyapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.listAgentMemoryHistory({ path: { "name": "name" } });listAgentSkillReviews
List agent skill reviews (experimental)
compozy.agents.listAgentSkillReviews({ query }) → Promise<AgentSkillReviewsResponse>
Options
- instance_idstringquery
- Instance ID
- workspacestringquery
- Workspace reference
- statestringquery
- pending, approved or rejected
- cursorstringquery
- Page cursor
- limitintegerquery
- Page size, 1-100; default 50
- profilestringquery
- Act as this profile by name
GET /api/agent-skill-reviewsapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.listAgentSkillReviews();listAgentSoulHistory
List managed SOUL.md authoring revisions
compozy.agents.listAgentSoulHistory({ path, query }) → Promise<AgentSoulHistoryResponse>
Options
- namestringpathrequired
- Agent name
- workspace_idstringquery
- Workspace id
- limitintegerquery
- Maximum number of revisions to return
- cursorstringquery
- Revision cursor
- profilestringquery
- Act as this profile by name
GET /api/agents/{name}/soul/historyapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.listAgentSoulHistory({ path: { "name": "name" } });listAgents
List all readable agent definitions, optionally resolved for a workspace
compozy.agents.listAgents({ query }) → Promise<AgentsResponse>
Options
- workspacestringquery
- Workspace id, name, or path used to resolve workspace-local agents
- profilestringquery
- Act as this profile by name
GET /api/agentsapp tokens allowed
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.listAgents();listAgentsAggregate
List a filtered agent fleet with exact session metrics
compozy.agents.listAgentsAggregate({ query }) → Promise<AgentCatalogResponse>
Options
- all_workspacesbooleanquery
- Read all projects and User rows
- workspace_idsstring[]query
- Repeatable project IDs or @user; requires all_workspaces=true
- group"agent"query
- Group identical scoped definitions
- namestringquery
- Exact agent name
- qstringquery
- Case-insensitive agent name, label or category search
- categorystringquery
- Exact category path joined by slash separators
- status"active" | "idle"query
- Agent session status
- cursorstringquery
- Opaque cursor bound to workspace and filters
- limitintegerquery
- Agents per page (1-100; default 50)
- profilestringquery
- Act as this profile by name
GET /api/agents/aggregateapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.listAgentsAggregate({ query: { "status": "active" } });markAgentInstanceSeen
Mark the instance seen by the local operator
compozy.agents.markAgentInstanceSeen({ path, query }) → Promise<AgentInstanceSeenResponse>
Options
- idstringpathrequired
- Instance ID
- profilestringquery
- Act as this profile by name
POST /api/agent-instances/{id}/awayapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.markAgentInstanceSeen({ path: { "id": "id" } });pauseAgentInstance
Pause an agent instance
compozy.agents.pauseAgentInstance({ path, query }) → Promise<AgentInstanceResponse>
Options
- idstringpathrequired
- Instance ID
- profilestringquery
- Act as this profile by name
POST /api/agent-instances/{id}/pauseapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.pauseAgentInstance({ path: { "id": "id" } });pickAgentInstanceProposal
Pick an instance proposal
compozy.agents.pickAgentInstanceProposal({ path, query, body }) → Promise<AgentInstancePickResponse>
Options
- idstringpathrequired
- Instance ID
- report_idstringpathrequired
- Report ID
- profilestringquery
- Act as this profile by name
Request bodyAgentInstancePickRequest
POST /api/agent-instances/{id}/reports/{report_id}/pickapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.pickAgentInstanceProposal({ path: { "id": "id", "report_id": "report_id" }, body: { /* request fields */ } });putAgentHeartbeat
Create or replace HEARTBEAT.md through managed authoring
compozy.agents.putAgentHeartbeat({ path, query, body }) → Promise<HeartbeatMutationResponse>
Options
- namestringpathrequired
- Agent name
- profilestringquery
- Act as this profile by name
Request bodyHeartbeatPutByPathRequest
PUT /api/agents/{name}/heartbeatapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.putAgentHeartbeat({ path: { "name": "name" }, body: { /* request fields */ } });putAgentMemory
Replace memory with a digest check (experimental)
compozy.agents.putAgentMemory({ path, query, body }) → Promise<AgentMemoryDocument>
Options
- namestringpathrequired
- Agent name
- workspacestringquery
- Workspace selecting the agent definition
- profilestringquery
- Act as this profile by name
Request bodyAgentMemoryWriteRequest
PUT /api/agents/{name}/memoryapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.putAgentMemory({ path: { "name": "name" }, body: { /* request fields */ } });putAgentSoul
Create or replace SOUL.md through managed authoring
compozy.agents.putAgentSoul({ path, query, body }) → Promise<AgentSoulMutationResponse>
Options
- namestringpathrequired
- Agent name
- profilestringquery
- Act as this profile by name
Request bodyAgentSoulPutByPathRequest
PUT /api/agents/{name}/soulapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.putAgentSoul({ path: { "name": "name" }, body: { /* request fields */ } });rejectAgentSkillReview
Decide a skill review as the operator (experimental)
compozy.agents.rejectAgentSkillReview({ path, query, body }) → Promise<AgentSkillReviewResponse>
Options
- idstringpathrequired
- Review ID
- profilestringquery
- Act as this profile by name
Request bodyAgentSkillReviewDecisionRequest
POST /api/agent-skill-reviews/{id}/rejectapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.rejectAgentSkillReview({ path: { "id": "id" }, body: { /* request fields */ } });removeAgentMemory
Remove matching memory entries (experimental)
compozy.agents.removeAgentMemory({ path, query, body }) → Promise<AgentMemoryRemoveResponse>
Options
- namestringpathrequired
- Agent name
- workspacestringquery
- Workspace selecting the agent definition
- profilestringquery
- Act as this profile by name
Request bodyAgentMemoryRemoveRequest
DELETE /api/agents/{name}/memory/entriesapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.removeAgentMemory({ path: { "name": "name" }, body: { /* request fields */ } });replaceAgentMemory
Replace matching memory text (experimental)
compozy.agents.replaceAgentMemory({ path, query, body }) → Promise<AgentMemoryDocument>
Options
- namestringpathrequired
- Agent name
- workspacestringquery
- Workspace selecting the agent definition
- profilestringquery
- Act as this profile by name
Request bodyAgentMemoryReplaceRequest
PATCH /api/agents/{name}/memory/entriesapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.replaceAgentMemory({ path: { "name": "name" }, body: { /* request fields */ } });resumeAgentInstance
Resume an agent instance
compozy.agents.resumeAgentInstance({ path, query }) → Promise<AgentInstanceResponse>
Options
- idstringpathrequired
- Instance ID
- profilestringquery
- Act as this profile by name
POST /api/agent-instances/{id}/resumeapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.resumeAgentInstance({ path: { "id": "id" } });revokeAgentHeartbeatAuthority
revoke check-in authority
compozy.agents.revokeAgentHeartbeatAuthority({ path, query }) → Promise<void>
Options
- namestringpathrequired
- Agent name
- workspace_idstringquery
- Workspace id
- profilestringquery
- Act as this profile by name
DELETE /api/agents/{name}/heartbeat/authority/approveapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.revokeAgentHeartbeatAuthority({ path: { "name": "name" } });revokeAgentHeartbeatScript
Revoke a source script approval (operator only)
compozy.agents.revokeAgentHeartbeatScript({ path, query }) → Promise<void>
Options
- namestringpathrequired
- Agent name
- scriptstringpathrequired
- Script name
- workspace_idstringquery
- Workspace id
- profilestringquery
- Act as this profile by name
DELETE /api/agents/{name}/heartbeat/scripts/{script}/approveapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.revokeAgentHeartbeatScript({ path: { "name": "name", "script": "script" } });rollbackAgentHeartbeat
Rollback HEARTBEAT.md through managed authoring
compozy.agents.rollbackAgentHeartbeat({ path, query, body }) → Promise<HeartbeatMutationResponse>
Options
- namestringpathrequired
- Agent name
- profilestringquery
- Act as this profile by name
Request bodyHeartbeatRollbackByPathRequest
POST /api/agents/{name}/heartbeat/rollbackapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.rollbackAgentHeartbeat({ path: { "name": "name" }, body: { /* request fields */ } });rollbackAgentMemory
Restore a memory revision (experimental)
compozy.agents.rollbackAgentMemory({ path, query, body }) → Promise<AgentMemoryDocument>
Options
- namestringpathrequired
- Agent name
- workspacestringquery
- Workspace selecting the agent definition
- profilestringquery
- Act as this profile by name
Request bodyAgentMemoryRollbackRequest
POST /api/agents/{name}/memory/rollbackapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.rollbackAgentMemory({ path: { "name": "name" }, body: { /* request fields */ } });rollbackAgentSoul
Rollback SOUL.md through managed authoring
compozy.agents.rollbackAgentSoul({ path, query, body }) → Promise<AgentSoulMutationResponse>
Options
- namestringpathrequired
- Agent name
- profilestringquery
- Act as this profile by name
Request bodyAgentSoulRollbackByPathRequest
POST /api/agents/{name}/soul/rollbackapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.rollbackAgentSoul({ path: { "name": "name" }, body: { /* request fields */ } });searchAgentMemory
Search agent notes and accessible sessions (experimental)
compozy.agents.searchAgentMemory({ path, query, body }) → Promise<AgentMemorySearchResponse>
Options
- namestringpathrequired
- Agent name
- workspacestringquery
- Workspace selecting the agent definition
- profilestringquery
- Act as this profile by name
Request bodyAgentMemorySearchRequest
POST /api/agents/{name}/memory/searchapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.searchAgentMemory({ path: { "name": "name" }, body: { /* request fields */ } });updateAgent
Replace one effective AGENT.md definition with digest CAS
compozy.agents.updateAgent({ path, query, body }) → Promise<AgentResponse>
Options
- namestringpathrequired
- Agent name
- profilestringquery
- Act as this profile by name
Request bodyUpdateAgentRequestWritable
PUT /api/agents/{name}app tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.updateAgent({ path: { "name": "name" }, body: { /* request fields */ } });updateAgentInstance
Update instance checks
compozy.agents.updateAgentInstance({ path, query, body }) → Promise<AgentInstanceResponse>
Options
- idstringpathrequired
- Instance ID
- profilestringquery
- Act as this profile by name
Request bodyAgentInstanceUpdateRequest
PATCH /api/agent-instances/{id}app tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.updateAgentInstance({ path: { "id": "id" }, body: { /* request fields */ } });validateAgentDefinitionSoul
Validate a proposed Soul body for an agent definition
compozy.agents.validateAgentDefinitionSoul({ path, query, body }) → Promise<AgentSoulPayload>
Options
- namestringpathrequired
- Agent name
- profilestringquery
- Act as this profile by name
Request bodyAgentSoulValidateByPathRequest
POST /api/agents/{name}/soul/validateapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.validateAgentDefinitionSoul({ path: { "name": "name" }, body: { /* request fields */ } });validateAgentHeartbeat
Validate a proposed HEARTBEAT.md body
compozy.agents.validateAgentHeartbeat({ path, query, body }) → Promise<HeartbeatPolicyPayload>
Options
- namestringpathrequired
- Agent name
- profilestringquery
- Act as this profile by name
Request bodyHeartbeatValidateByPathRequest
POST /api/agents/{name}/heartbeat/validateapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.validateAgentHeartbeat({ path: { "name": "name" }, body: { /* request fields */ } });validateAgentMemory
Validate proposed memory content (experimental)
compozy.agents.validateAgentMemory({ path, query, body }) → Promise<AgentMemoryValidateResponse>
Options
- namestringpathrequired
- Agent name
- workspacestringquery
- Workspace selecting the agent definition
- profilestringquery
- Act as this profile by name
Request bodyAgentMemoryValidateRequest
POST /api/agents/{name}/memory/validateapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.validateAgentMemory({ path: { "name": "name" }, body: { /* request fields */ } });wakeAgentHeartbeat
Request one advisory Heartbeat wake for an eligible session
compozy.agents.wakeAgentHeartbeat({ path, query, body }) → Promise<HeartbeatWakeResponse>
Options
- namestringpathrequired
- Agent name
- profilestringquery
- Act as this profile by name
Request bodyHeartbeatWakeByPathRequest
POST /api/agents/{name}/heartbeat/wakeapp tokens denied
import { Compozy } from "@compozy/client"; const compozy = await Compozy.connect();const result = await compozy.agents.wakeAgentHeartbeat({ path: { "name": "name" }, body: { /* request fields */ } });