# Get a Durable Agent

`GET /apis/cra.diagrid.io/v1beta1/projects/{ProjectId}/durableagents/{AgentId}`

Get the details of a Durable Agent.

## Request

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `ProjectId` | string | Yes | Unique identifier of the project. |
| `AgentId` | string | Yes | Unique identifier of the agent. |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `noextramapping` | boolean | No | Skip loading extra related data and return only the resource metadata and spec. |
| `include` | string[] | No | Related data to include in the response. |

## Responses

### 200 — The requested Durable Agent.

`application/json`

- `apiVersion` (string)
- `kind` (string)
- `metadata` (object)
  - `name` (string)
  - `uid` (string)
  - `resourceVersion` (integer)
  - `createdAt` (string)
  - `updatedAt` (string)
  - `deletedAt` (string)
  - `labels` (object<string, string>)
  - `annotations` (object)
- `spec` (object) — Required.
  - `projectId` (string) — Required. Read-only. Immutable. ProjectID is server-derived from the request path; the client-supplied value is ignored.
  - `role` (string) — Required.
  - `goal` (string)
  - `instructions` (string[])
  - `llmComponentName` (string) — LLMComponentName references an existing conversation component by name. Mutually exclusive with LLMConfig.
  - `llmConfig` (object) — LLMConfig defines inline LLM provider configuration for a DurableAgent. The provider suffix matches the Dapr conversation component type suffix (e.g. "openai" → type "conversation.openai").
    - `provider` (string) — Required. Provider is the conversation provider suffix (e.g. "openai", "anthropic").
    - `apiKey` (string) — APIKey is the provider API key. Write-only: it is cleared from the spec once stored securely, and responses never include it.
    - `model` (string) — Required. Model is the LLM model name (e.g. "gpt-4o", "claude-3-5-sonnet-20241022").
    - `endpoint` (string) — Endpoint is an optional custom HTTP endpoint for the conversation component (e.g. "https://openrouter.ai/api/v1" to route OpenAI-compatible traffic through OpenRouter). Only supported when Provider is "openai".
  - `sandbox` (object) — SandboxSpec is the per-DurableAgent sandbox opt-in.
    - `enabled` (boolean) — Enabled, when true, enables the sandbox and registers the built-in filesystem and exec tools (fs_*/exec_*) on the agent.
    - `git` (object) — GitSpec opts the agent into the typed git_* tool surface. Credentials never reach the agent process; short-lived, per-repo tokens are issued on demand instead.
      - `provider` (object) — GitProvider is a vendor-tagged union: exactly one variant is set and validation rejects multi-set specs.
        - `githubApp` (object) — GitHubAppSpec carries the GitHub App identity and PEM private key. PrivateKey is write-only: a GET returns the field cleared, and an update that omits it keeps the existing key.
          - `appId` (string) — Required. AppID is the GitHub App ID.
          - `installationId` (string) — Required.
          - `privateKey` (string)
          - `apiBaseUrl` (string) — APIBaseURL targets GitHub Enterprise (e.g. "https://github.example.com/api/v3"). Empty means api.github.com.
      - `repos` (object[]) — Required. Repos is the inline allowlist. The agent passes a logical repo Name to the git_* tools, which is resolved to the repository URL. Min items: 1.
        - `name` (string) — Required. Name is the logical handle passed as the repo_name argument to the git tools. Must be unique; names starting with an underscore are reserved.
        - `url` (string) — Required. URL is the HTTPS clone URL. SSH URLs are not supported.
        - `branch` (string)
        - `allowedPaths` (string[]) — AllowedPaths are doublestar globs restricting which paths the agent can stage and commit. Empty means no restriction.
        - `pushPolicy` (object) — PushPolicy bounds the refs an agent may push to.
          - `branchPrefix` (string) — BranchPrefix restricts push targets. Defaults to "catalyst/" when empty.
          - `allowPushToDefaultBranch` (boolean) — AllowPushToDefaultBranch lifts the default-branch protection. Defaults to false to protect the repository's default branch from unintended pushes by the agent.
        - `unauthenticated` (boolean) — Unauthenticated marks the repo as public: it is cloned and fetched anonymously and pushes are rejected. Required when GitSpec.Provider is unset.
      - `pushPolicy` (object) — PushPolicy bounds the refs an agent may push to.
        - `branchPrefix` (string) — BranchPrefix restricts push targets. Defaults to "catalyst/" when empty.
        - `allowPushToDefaultBranch` (boolean) — AllowPushToDefaultBranch lifts the default-branch protection. Defaults to false to protect the repository's default branch from unintended pushes by the agent.
  - `webTools` (object) — WebToolsSpec is the per-DurableAgent opt-in for the built-in web_search and web_fetch tools.
    - `enabled` (boolean) — Enabled, when true, registers the built-in web_search and web_fetch tools on the DurableAgent.
- `status` (object) — DurableAgentStatus is the observed state of a DurableAgent.
  - `status` (string)
  - `messages` (object[])
    - `message` (string)
  - `processedSpecVersion` (integer (int64)) — ProcessedSpecVersion is the spec version reflected in this status.
  - `instances` (object<string, object>) — Instances holds the resource's processing status keyed by the region host it runs on.
    - `status` (string)
    - `messages` (object[])
      - `message` (string)
    - `processedSpecVersion` (integer (int64))
    - `regionHostId` (string)
  - `managedAppId` (string) — ManagedAppID is the name of the AppID automatically provisioned and managed for this DurableAgent.
  - `managedLLMComponent` (string) — ManagedLLMComponent is the name of the conversation Connection automatically provisioned for this DurableAgent. Set only when LLMConfig was supplied; empty when an existing Connection is referenced via LLMComponentName.
  - `managedSandbox` (string) — ManagedSandbox is the name of the sandbox automatically provisioned for this DurableAgent. Empty when sandbox support is disabled for the region or before the sandbox has been created.
  - `appIds` (object[]) — AppIDs embeds the AppID this DurableAgent owns and manages, including its status.apiToken. Populated only when a Get request carries include=appids.
    - `apiVersion` (string) — Required.
    - `kind` (string) — Required.
    - `metadata` (object) — Required.
      - `uid` (string)
      - `name` (string) — Required.
      - `namespace` (string) — Required.
      - `resourceVersion` (integer (int64))
      - `statusVersion` (integer (int64))
      - `createdAt` (string)
      - `updatedAt` (string)
      - `deletedAt` (string)
      - `finalizers` (string[]) — if no finalizers are set the resource will be deleted from the database directly when calling MarkForDelete, delete event is fired normally then the event dispatcher will detect that situation and delete the resource from the cache.
      - `annotations` (object)
      - `hash` (string)
      - `labels` (object<string, string>)
    - `spec` (object) — Required. AppIdentitySpec is the user-facing specification of an App ID.
      - `projectId` (string) — Required. Read-only. Immutable. ProjectID is server-derived from the request path; the client-supplied value is ignored.
      - `apiTokenRevision` (integer)
      - `appEndpoint` (object) — AppEndpoint is the application endpoint configuration of an App ID.
        - `url` (string)
        - `clientTimeoutSeconds` (integer)
        - `token` (string) — Write-only. Token authenticates calls from the dataplane to the app endpoint. It can only be written: responses never include it, the app token is only returned as .status.appToken.
      - `healthCheck` (object)
        - `path` (string) — used for HTTP e.g. /health.
        - `probe` (object)
          - `enabled` (boolean)
          - `intervalInSec` (integer (int32))
          - `timeoutInMs` (integer (int32))
          - `failureThreshold` (integer (int32))
      - `protocol` (string)
      - `appConfig` (string)
      - `resiliency` (object)
        - `retryPolicyName` (string)
        - `timeoutPolicyName` (string)
        - `circuitBreakerPolicyName` (string)
      - `maxBodySize` (string)
      - `external` (boolean) — Immutable.
      - `appContainer` (object) — AppContainerSpec holds configuration for an app container that runs alongside a sidecar.
        - `image` (string)
        - `port` (integer)
        - `pullPolicy` (string)
        - `command` (string[])
        - `args` (string[])
        - `env` (object<string, string>)
        - `files` (object<string, string>)
      - `workflowArchive` (object) — WorkflowArchiveSpec selects which terminal workflow states have their history archived on purge and where the archive is written. Archiving is enabled when a destination binding is set.
        - `completed` (boolean) — Completed archives workflows that reach the Completed terminal state.
        - `failed` (boolean) — Failed archives workflows that reach the Failed terminal state.
        - `terminated` (boolean) — Terminated archives workflows that reach the Terminated terminal state.
        - `destination` (object) — WorkflowArchiveDestination identifies the archive output binding.
          - `binding` (string) — Binding is the output-binding component name. Empty disables archiving.
          - `type` (string) — Type is the binding component type (e.g. "bindings.aws.s3").
      - `workflowNotifications` (object) — WorkflowNotificationsSpec selects which workflow outcomes raise an alert. Completed workflows are not selectable: the policy reports outcomes that need someone's attention.
        - `name` (string) — Name is a regular expression the workflow name must match in full. Empty matches every workflow.
        - `failed` (boolean) — Failed notifies workflows that reach the Failed terminal state.
        - `terminated` (boolean) — Terminated notifies workflows that reach the Terminated terminal state.
        - `stalled` (boolean) — Stalled notifies workflows that reach the Stalled state.
        - `rootOnly` (boolean) — RootOnly restricts notifications to workflows with no parent, so one failing parent does not also alert for each of its children.
    - `status` (object) — AppIdentityStatus represents the status of an application identity.
      - `status` (string) — Status is the current processing status of the resource.
      - `updatedAt` (string) — UpdatedAt is the time of the last status update.
      - `messages` (object[]) — Messages contains any status messages, such as error details.
        - `message` (string)
      - `instances` (object[]) — Instances includes the status for each instance of the resource.
        - `cluster` (string) — Cluster is the name of the cluster hosting this instance.
        - `region` (string) — Region is the region where the instance is located (e.g. "us-east-1").
        - `placementId` (string) — PlacementID is the project placement this instance belongs to (e.g. "1").
        - `status` (string) — Status is the current processing status of the resource.
        - `updatedAt` (string) — UpdatedAt is the time of the last status update.
        - `messages` (object[]) — Messages contains any status messages, such as error details.
          - `message` (string)
      - `apiToken` (string) — APIToken is omitted unless the caller has the appIdCredentials.get permission.
      - `appToken` (string)
      - `resiliencyStatus` (object)
        - `retryPolicyName` (string)
        - `timeoutPolicyName` (string)
        - `circuitBreakerPolicyName` (string)
      - `resiliency` (object)
        - `projectId` (string) — Required. Immutable.
        - `resiliencySpec` (object) — Required. ResiliencySpec is the Dapr resiliency specification (policies and targets), based on the upstream Dapr Resiliency API. Fields present upstream but not listed here are not supported in Catalyst.
          - `policies` (object)
            - `timeouts` (object<string, string>)
            - `retries` (object<string, object>)
              - *(nested fields omitted at this depth)*
            - `circuitBreakers` (object<string, object>)
              - *(nested fields omitted at this depth)*
          - `targets` (object)
            - `apps` (object<string, object>)
              - *(nested fields omitted at this depth)*
            - `components` (object<string, object>)
              - *(nested fields omitted at this depth)*
        - `scopes` (string[])
      - `spiffeId` (string) — SpiffeID is the single workload identity this App ID is reported under: the identity it is issued in the first of its project's regions by name. It does not move when a region is promoted, and a workload running in any other region of the project presents a different identity. Use regionIdentities to pre-trust the identity of every region instead of following this one.
      - `spiffeIds` (string[]) — SpiffeIDs is every workload identity this App ID is issued, one per region its project is placed in, in the same order as regionIdentities. Deprecated: use regionIdentities instead, which names the region each identity belongs to.
      - `regionIdentities` (object[]) — RegionIdentities lists the workload identity this App ID is issued in every region its project is placed in, one entry per region, ordered by region name. It is spiffeIds with the region each identity belongs to named, so a reader does not have to take it from the trust domain. Pre-trust every entry in an external identity federation: a project spread over a region group runs under a different identity in each of its regions, and which one a workload presents follows the region it runs in. The OIDC issuer that verifies JWTs minted for an identity is the region's, and is read from that region (status.endpoints.oidc).
        - `region` (string) — Region is the region the identity is issued in. Read that region to get the OIDC issuer verifying JWTs minted for this identity, and the trust anchors verifying its certificates: both are region properties, served on the region's own status.endpoints.
        - `spiffeId` (string) — SpiffeID is the SPIFFE ID workloads of this App ID present in that region.
      - `externalBootstrapConfig` (string) — ExternalBootstrapConfig is the bootstrap YAML configuration for external appIDs. It contains everything an external workload needs to connect to the data plane, including the required endpoints and the join token.
      - `isActive` (boolean) — IsActive indicates if the app identity is active, if the sidecar has performed API operations recently.
      - `workflowsConnected` (boolean) — WorkflowsConnected indicates if the app identity has workflow workers currently connected.
      - `clientType` (string) — ClientType is the identity-view classification of this App ID — "app", "agent", or "mcpserver".
      - `appEndpointStatus` (string) — Deprecated: use appHealthCheckStatus instead.
      - `appHealthCheckStatus` (object) — AppIdentityAppHealthCheckStatus represents the health check status of an application identity.
        - `ishealthy` (boolean)
        - `timestamp` (string)
        - `reason` (string)
      - `events` (object) — AppIdentityEvents represents events from an application identity.
        - `errors` (object[])
          - `cluster` (string) — Cluster is the name of the cluster the event originated from.
          - `message` (string)
          - `timestamp` (string (date-time))

Example:

```json
{
  "apiVersion": "cra.diagrid.io/v1beta1",
  "kind": "DurableAgent",
  "metadata": {
    "name": "support-agent"
  },
  "spec": {
    "projectId": "my-project",
    "role": "customer support agent",
    "goal": "Resolve customer enquiries using the order tools.",
    "instructions": [
      "Be concise.",
      "Escalate refunds to a human."
    ],
    "llmConfig": {
      "provider": "openai",
      "apiKey": "<api-key>",
      "model": "gpt-4o"
    }
  }
}
```

### 404 — The Durable Agent was not found.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

### default — Unexpected error.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.