---
title: "Get agent"
method: GET
path: "/agents/{agentKey}"
tags: ["Agents"]
---

# Get agent

`GET /agents/{agentKey}`

Retrieve agent details by its unique key.

**Gateway not-found behavior:**
Unknown `agentKey`, lookup after soft-delete, and other AI-backend failures
that return 404 from the Python query service are surfaced by the Node
gateway as **HTTP 404** with an `ErrorResponse` body.

## Path parameters

- `agentKey` string, required

## Response `200`

Agent details

- GetAgentResponse — Success envelope returned by `GET /agents/{agentKey}`. The Node gateway forwards the backend response as an envelope with a top-level status/message and the detailed agent projection nested under `agent`.
  - `status` string, required
  - `message` string, required
  - `agent` Agent, required — Detailed agent projection returned by agent detail-style endpoints such as `GET /agents/{agentKey}`.
    - `_id` string, required — Full document id in the backing graph store.
    - `_key` string, required — Stable agent key used in route params.
    - `_rev` string — Backend document revision token.
    - `name` string, required — Display name of the agent
    - `description` string — What this agent is designed to do
    - `systemPrompt` string — System instructions that define agent behavior
    - `createdBy` string, objectId, required — MongoDB user ID of the agent creator
    - `startMessage` string — Initial greeting shown when a conversation with this agent starts
    - `instructions` string, nullable — Additional agent execution instructions
    - `models` union[], required — Configured model entries for this agent.
      - union
        - string
        - object
          - `modelKey` string
          - `modelName` string
          - `provider` string
          - `isReasoning` boolean
          - `isMultimodal` boolean
          - `isDefault` boolean
          - `modelType` string — Model category. Must be `llm` for agent model entries (same value as `ModelType` for LLMs; string only — enum is not used here).
          - `modelFriendlyName` string
    - `toolsets` Toolset[], required — Toolset instances linked to the agent (GET /agents/{agentKey} graph projection). Multiple instances of the same integration type are distinguished by `instanceId` and optional `instanceName`.
      - `_key` string — Toolset instance node key in the backing graph store.
      - `name` 'calendar' | 'clickup' | 'confluence' | 'drive' | 'github' | 'gmail' | 'jira' | 'lumos' | 'mariadb' | 'onedrive' | 'outlook' | 'redshift' | 'salesforce' | 'sharepoint' | 'slack' | 'teams' | 'zoom' — Registered toolset name (lowercase) accepted by the create-agent gateway.
      - `displayName` string — Human-readable toolset product label (for example `Jira` or `Slack`).
      - `type` string
      - `instanceId` string — Admin-created toolset instance id
      - `instanceName` string — Human-readable instance label (e.g. sidebar instance name)
      - `selectedTools` string[], nullable — Tool names explicitly selected for this toolset instance, when the instance was created with a subset selection. `null`/absent when the instance exposes all of the toolset's tools.
      - `tools` object[]
        - `_key` string — Tool node key in the backing graph store.
        - `name` string
        - `fullName` string
        - `toolsetName` string — Toolset type key the tool belongs to.
        - `description` string
        - `deprecated` boolean — Server-stamped on `GET /agents/{agentKey}`: `true` when the tool's `fullName` is no longer in the runtime tool registry (its `@tool` was removed). Read-only; ignored on create/update bodies. Not stamped on the `GET /agents` list projection.
    - `knowledge` Knowledge[], required — Knowledge connectors and indexed scopes linked to the agent
      - `_key` string
      - `connectorId` string
      - `name` string
      - `type` string
      - `displayName` string
      - `filters` union — Knowledge scope filter as stored on the graph edge. The Node `getAgent` handler proxies this field unchanged from the AI service (only `agent.id` is stripped). May be a JSON string (typical graph storage) or an object. Prefer `filtersParsed` on GET for a guaranteed parsed object with the same keys as the object branch below.
        - AgentKnowledgeFiltersParsed — Indexed scope for a knowledge connector: record-group ids (collections / KB roots) and individual record ids. First-party create/update flows set `recordGroups` and `records`. On GET, `filtersParsed` is this shape parsed from the stored `filters` JSON string.
          - `recordGroups` string[] — Record-group ids (e.g. knowledge-base roots) in scope.
          - `records` string[] — Individual record ids in scope.
        - string — JSON-encoded filter object (graph storage format).
      - `filtersParsed` AgentKnowledgeFiltersParsed — Indexed scope for a knowledge connector: record-group ids (collections / KB roots) and individual record ids. First-party create/update flows set `recordGroups` and `records`. On GET, `filtersParsed` is this shape parsed from the stored `filters` JSON string.
        - `recordGroups` string[] — Record-group ids (e.g. knowledge-base roots) in scope.
        - `records` string[] — Individual record ids in scope.
    - `shareWithOrg` boolean, required — Whether the agent is shared with the whole organization
    - `webSearch` object, nullable — Web search provider attached to this agent. Null when none is configured.
      - `provider` string, required — Provider identifier (e.g. "tavily", "serper", "exa", "duckduckgo")
      - `providerKey` string
      - `providerLabel` string
    - `tags` string[], required — Free-form agent tags.
    - `createdAtTimestamp` integer, required — Unix epoch timestamp in milliseconds when the agent was created.
    - `updatedAtTimestamp` integer, required — Unix epoch timestamp in milliseconds when the agent was last updated.
    - `updatedBy` string, nullable — User id of the last updater, if present.
    - `isActive` boolean, required — Whether the agent is active.
    - `isDeleted` boolean, required — Whether the agent has been soft-deleted.
    - `isServiceAccount` boolean, required — Whether this agent is a service-account agent.
    - `access_type` string, required — How the user can access this agent.
    - `user_role` string, required — Effective role of the current user on this agent.
    - `can_view` boolean, required — Effective permission to view the agent.
    - `can_share` boolean, required — Effective permission to share the agent.
    - `can_edit` boolean, required — Effective permission to edit the agent.
    - `can_delete` boolean, required — Effective permission to delete the agent.

## Other responses

- `400` — Gateway validation failure (non-empty `agentKey` path param) or missing organization/user context on the authenticated request.
- `401` — Missing or invalid bearer token (e.g. `No token provided`)
- `403` — Forbidden — insufficient OAuth scope (`agent:read` required)
- `404` — Agent not found, inaccessible, or previously deleted.
- `500` — Unexpected AI-backend or gateway failure.
- `503` — AI query service unreachable

---

[API](https://skmtc.net/pipeshub-ai/apis/pipeshub-api.md) · [All operations](https://skmtc.net/pipeshub-ai/apis/pipeshub-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pipeshub-ai/pipeshub-api/versions/abd27cfefc73/schema)