@spec agent_health_actions(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.GetApiV1AgentsAgentAgentHealthActions.Params.t()
) ::
  {:ok, ArchAstro.Types.HealthActionListResponse.t()}
  | {:error, ArchAstro.Error.reason()}

List health actions for an agent

Returns all health actions associated with a given agent. Health actions represent required or recommended steps — such as setting environment variables, completing OAuth installations, or running custom verifiers — that an agent needs to reach a healthy state.

Results are not paginated; the full list for the agent is returned. Use the source, status, and kind filters to narrow results to the subset your UI or workflow needs. Multiple values for the same filter are treated as OR (e.g. passing two statuses returns actions matching either). The caller must be authenticated and scoped to the app that owns the agent.

Object containing a data array of health action objects for the specified agent.

@spec agent_routines(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PostApiV1AgentsAgentAgentRoutines.Input.t()
) ::
  {:ok, ArchAstro.Types.AgentRoutine.t()} | {:error, ArchAstro.Error.reason()}

Create a routine

Creates a new routine and attaches it to the specified agent. Routines define how an agent responds to events or a cron schedule; the handler_type controls which execution model is used.

The routine is created in "draft" status by default. To start processing events immediately, either pass status: "active" or call the activate endpoint after creation. Scheduled routines must run no more frequently than once per hour. Requires app scope.

The newly created routine.

@spec create(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1Agents.Input.t()
) ::
  {:ok, ArchAstro.Types.AgentCreateResponse.t()}
  | {:error, ArchAstro.Error.reason()}

Create an agent

Creates a new agent. Supports two mutually exclusive provisioning modes.

Template mode — pass template with the ID or lookup_key of an existing AgentTemplate config. The agent's tools, routines, skills, and installations are provisioned from that template's config_ref entries.

Bundle mode — pass template_bundle with a self-contained install payload (AgentTemplate body plus every skill, script, and config it references). The entire bundle commits in a single transaction; any failure rolls back the whole install and the response includes installed_configs[] — one entry per persisted config.

Pass exactly one of template or template_bundle. If neither is supplied, name is required and a blank agent is created. Requires authentication; when called under a developer app scope (/developer/apps/:app/...), the caller must hold the app scope for the target app.

The newly created agent. When template_bundle was supplied, the response also includes installed_configs[] — one entry per persisted config object, with key echoing the caller-supplied input identifier.

@spec delete(ArchAstro.Client.t(), String.t()) ::
  {:ok, :ok} | {:error, ArchAstro.Error.reason()}

Delete an agent

Permanently deletes an agent and all of its associated resources. This action cannot be undone.

The authenticated caller must own the agent or hold sufficient permissions within its owning org or team. When called under a developer app scope, the caller must hold the app scope for the target app.

Empty body. Returns HTTP 204 on success.

@spec export(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.GetApiV1AgentsAgentExport.Params.t()
) :: {:ok, ArchAstro.Types.AgentExport.t()} | {:error, ArchAstro.Error.reason()}

Export an agent as an AgentTemplate

Reconstructs an AgentTemplate config from a deployed agent and all of its sub-resources (tools, routines, skills, installations). Returns the template definition together with every dependent config file (scripts, workflows, skills, schemas) and their raw content, producing a fully self-contained export bundle.

Use this endpoint to snapshot an agent's current configuration for backup, migration, or to seed a new Solution template. Pass remove_identity: true to strip instance-specific fields (email, phone number) before export.

The authenticated caller must own the agent or hold sufficient permissions within its owning org or team. When called under a developer app scope, the caller must hold the app scope for the target app.

Export bundle containing the reconstructed AgentTemplate and all dependent config files with their raw content.

@spec get(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.Agent.t()} | {:error, ArchAstro.Error.reason()}

Retrieve an agent

Returns the agent identified by ID or lookup_key. The authenticated caller must own the agent or hold sufficient permissions within its owning org or team.

When called under a developer app scope, the agent must belong to that app. Use the list endpoint to retrieve many agents at once.

The requested agent.

@spec health(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.AgentHealth.t()} | {:error, ArchAstro.Error.reason()}

Retrieve an agent's health profile

Returns an aggregate health profile for the specified agent, including an overall status, a numeric health score, recent activity metrics, and a list of recommended remediation actions.

The health check is computed on demand at request time. The checked_at timestamp in the response reflects when the evaluation ran. Use this endpoint to surface diagnostics about tool availability, model configuration, and runtime activity in dashboards or monitoring workflows.

The authenticated caller must own the agent or hold sufficient permissions within its owning org or team. When called under a developer app scope, the caller must hold the app scope for the target app.

Aggregate health profile for the agent, including status, score, activity metrics, and recommended actions.

@spec list(ArchAstro.Client.t(), ArchAstro.Types.Operations.GetApiV1Agents.Params.t()) ::
  {:ok, ArchAstro.Types.AgentListResponse.t()}
  | {:error, ArchAstro.Error.reason()}

List agents

Returns a paginated list of agents visible to the authenticated caller. Results are ordered by creation time descending.

Use search to filter by name, org, team, or owner fields. Use user or org_id to scope the list to a specific owner. Use template_config to find agents whose last applied template matches a given config ID. Use solution_config to find agents whose last applied template was imported as part of any of the given Solution config IDs.

Pagination is page-based: pass page and page_size to navigate through large result sets. When called under a developer app scope, only agents belonging to that app are returned.

Paginated list of agents matching the supplied filters.

@spec search(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PostApiV1AgentsAgentSearch.Input.t()
) ::
  {:ok, ArchAstro.Types.Operations.PostApiV1AgentsAgentSearch.Response.t()}
  | {:error, ArchAstro.Error.reason()}

Search an agent's knowledge base

Performs a semantic search over an agent's knowledge base and returns a ranked, kind-discriminated list of matching items.

Two item kinds may appear in data:

• "chunk" — chunk-level results from the agent's context store. Present for all agents.
• "document" — document-level results. Present only when the agent has an active archastro/knowledge installation.

Results from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to be comparable across kinds, then merged into a single ranked list. On a relevance tie, chunks appear before documents. The total number of results is capped at max_results across both kinds.

Use mode to choose the retrieval strategy: "hybrid" (default) combines vector and full-text search; "vector" and "fulltext" select each strategy independently.

Successful response

@spec threads(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PostApiV1AgentsAgentThreads.Input.t()
) :: {:ok, ArchAstro.Types.Thread.t()} | {:error, ArchAstro.Error.reason()}

Create a thread for an agent

Creates a new thread owned by the specified agent. The thread is scoped to the agent's identity and is immediately available for messaging.

The authenticated caller must have access to the agent's parent app. If your API key is scoped to a specific app, pass that app's ID via the app parameter. Attempting to create a thread for an agent you cannot access returns 404.

By default the platform may send an automatic welcome message into the new thread. Pass skip_welcome_message: true to suppress this behavior.

The newly created thread.

@spec update(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PatchApiV1AgentsAgent.Input.t()
) :: {:ok, ArchAstro.Types.Agent.t()} | {:error, ArchAstro.Error.reason()}

Update an agent

Updates one or more fields on an existing agent. Only the fields you supply are changed; omitted fields retain their current values.

To clear the agent's default model, pass model as an empty string. The authenticated caller must own the agent or hold write permissions within its owning org or team. When called under a developer app scope, the caller must hold the app scope for the target app.

The updated agent with all current field values.

@spec upgrade(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PostApiV1AgentsAgentUpgrade.Input.t()
) ::
  {:ok, ArchAstro.Types.AgentUpgradeResponse.t()}
  | {:error, ArchAstro.Error.reason()}

Upgrade an agent from an AgentTemplate

Upgrades an existing agent by reconciling it against an AgentTemplate from a Solution. Supports two modes:

• "reapply" (default) — re-applies the agent's currently tracked template, picking up any changes the template author has made since the last apply.
• "replace" — moves the agent to a different template. template is required in this mode.

Set dry_run: true to compute and return the full upgrade diff (adds, updates, removes, noops) without writing any changes. The response includes a review_fingerprint you can pass back via expected_review_fingerprint on the live apply to guard against the diff changing between review and execution.

Safe overrides (name, description, email, phone_number, metadata, identity, originator, model) let you pin instance-specific values that should not be overwritten by the template during the upgrade.

The authenticated caller must own the agent or hold write permissions within its owning org or team. When called under a developer app scope, the caller must hold the app scope for the target app.

The upgrade outcome, including the updated agent, the source Solution and template summaries, and the full diff (upgrade_result) with status, dry-run flag, aggregate counts, and a per-resource change list. When dry_run is true, agent is null and no changes are persisted.