> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Agent

> Retrieve an agent in a simplified view: its attached skills as one flat list, plus core configuration.

Returns a **simplified agent view** (`SimplifiedAIAgent`), not the full object that [Create Agent](/api-reference/v1/agents/create-agent) returns. Instead of the low-level `graph`, `attached_tools`, `oas`, and fully-resolved skill schemas, the agent's attached skills are surfaced as one flat `tools` array (see the `AgentTool` shape below). Use [Add Agent Tool](/api-reference/v1/agents/tools/add-agent-tool) and [Remove Agent Tool](/api-reference/v1/agents/tools/remove-agent-tool) to change them. Fields such as `skills`, `gated_commands`, `secret_bindings`, `can_self_schedule` and `default_user_id` are not part of this view; they come back on the full object that [Create Agent](/api-reference/v1/agents/create-agent) and [Update Agent](/api-reference/v1/agents/update-agent) return.

## Path Parameters

<ParamField path="agent_id" type="string" required>
  Unique identifier of the agent (UUID format)
</ParamField>

## Response

<ResponseField name="id" type="string">Agent UUID</ResponseField>
<ResponseField name="name" type="string">Display name</ResponseField>
<ResponseField name="description" type="string">What the agent does (auto-generated on deploy from `instructions`)</ResponseField>
<ResponseField name="icon" type="string">Icon shown next to the agent name (default `xpi:workflow:dusk`, or an emoji)</ResponseField>
<ResponseField name="type" type="string">Agent type: `manager`, `regular`, `a2a`, `curl` or `orchestration`</ResponseField>
<ResponseField name="status" type="string">`DRAFT`, `ACTIVE` (deployed) or `INACTIVE`</ResponseField>
<ResponseField name="model_provider" type="string">LLM provider (e.g., `anthropic`)</ResponseField>
<ResponseField name="model_name" type="string">LLM model (e.g., `claude-sonnet-5`)</ResponseField>
<ResponseField name="framework" type="string">How the agent runs: `external-harness` (a coding CLI chosen by `harness_settings.default_cli`) or `agno` (the built-in loop)</ResponseField>
<ResponseField name="deployment_type" type="string">`serverless` or `container`</ResponseField>

<ResponseField name="harness_settings" type="object | null">
  Runtime settings of an `external-harness` agent; `null` for `agno`.

  <Expandable title="Harness Settings">
    <ResponseField name="permission_mode" type="string">`full` (default) or `gated`</ResponseField>
    <ResponseField name="max_concurrent_tasks" type="integer">Parallel task limit (default 12)</ResponseField>
    <ResponseField name="workdir_gc_days" type="integer">Idle working-directory retention in days (default 14)</ResponseField>
    <ResponseField name="approval_hold_hours" type="integer">Hours a turn waits for an approval (default 4)</ResponseField>
    <ResponseField name="default_cli" type="string">`claude-code`, `codex` or `opencode`</ResponseField>
    <ResponseField name="models" type="object">Model per CLI, for example `{"claude-code": "claude-sonnet-5"}`</ResponseField>
    <ResponseField name="available_clis" type="string[]">CLIs the agent's runtime reports as installed</ResponseField>
    <ResponseField name="runtime" type="string">`fleet` or `legacy`</ResponseField>
    <ResponseField name="resources" type="object | null">Per-turn sandbox ceilings (`memory_limit`, `memory_high`, `cpu`, `pids`, `disk`)</ResponseField>
    <ResponseField name="image_tag" type="string | null">Harness image build, when pinned</ResponseField>
    <ResponseField name="cli_auto_update" type="boolean">Always `true`; the platform keeps the CLIs current</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="instructions" type="object">
  <Expandable title="Instructions">
    <ResponseField name="role" type="string[]">Role statements</ResponseField>
    <ResponseField name="goal" type="string[]">Goals</ResponseField>
    <ResponseField name="general" type="string">Free-form general instructions</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="knowledge_base_ids" type="string[]">IDs of attached knowledge bases</ResponseField>
<ResponseField name="source_node_types" type="string[]">Trigger source types (e.g., `sdk`, `webhook`, `slack`)</ResponseField>

<ResponseField name="tools" type="array">
  The agent's attached skills, unified across kinds; capabilities the runtime provides on its own do not appear here. Each item is an `AgentTool`:

  <Expandable title="AgentTool">
    <ResponseField name="id" type="string">Stable handle for this attached tool. Pass it to [Remove Agent Tool](/api-reference/v1/agents/tools/remove-agent-tool).</ResponseField>
    <ResponseField name="type" type="string">One of `action`, `custom_function`, `mcp`, `agent`, `workflow`.</ResponseField>
    <ResponseField name="name" type="string | null">Human-readable tool name.</ResponseField>
    <ResponseField name="connection_id" type="string | null">Connector connection id. `action` only.</ResponseField>
    <ResponseField name="operation_id" type="string | null">Operation catalog id. `action` only.</ResponseField>
    <ResponseField name="operation_name" type="string | null">OpenAPI operationId. `action` only.</ResponseField>
    <ResponseField name="custom_function_id" type="string | null">Custom function id. `custom_function` only.</ResponseField>
    <ResponseField name="mcp_id" type="string | null">MCP registry id. `mcp` only.</ResponseField>
    <ResponseField name="allowed_tools" type="string[] | null">Subset of MCP tools exposed. `mcp` only.</ResponseField>
    <ResponseField name="target_id" type="string | null">Referenced sub-agent or workflow id. `agent` / `workflow` only.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">ISO 8601 creation timestamp</ResponseField>
<ResponseField name="created_by" type="string | null">UUID of the creating user</ResponseField>

<ResponseField name="created_by_details" type="object | null">
  Resolved creator details (`null` when unavailable; null-check before reading).

  <Expandable title="Created By Details">
    <ResponseField name="id" type="string">User UUID</ResponseField>
    <ResponseField name="name" type="string">Display name (falls back to email/id)</ResponseField>
    <ResponseField name="email" type="string">User email</ResponseField>
  </Expandable>
</ResponseField>


## OpenAPI

````yaml GET /v1/agents/{agent_id}
openapi: 3.1.0
info:
  title: xpander.ai API Service
  description: |2-

        The xpander.ai API Service provides a unified REST API for managing AI agents,
        executing tasks, managing knowledge bases, and integrating with external systems.
        
        Features:
        - Agent Management: Create, update, deploy, and delete AI agents
        - Task Execution: Invoke agents with support for sync, async, and streaming modes
        - Knowledge Bases: Manage knowledge bases and documents for RAG workflows
        - Tools: Discover, connect, and attach tools (connectors, custom functions, MCP servers, sub-agents, workflows) to agents and workflows
        - MCP Integration: Model Context Protocol support for standardized AI interactions
        
        Authentication: All endpoints require authentication via either an API key (`x-api-key`) or an OAuth2 JWT (`Authorization: Bearer <jwt>`).
        
  version: '0.001'
servers:
  - url: https://api.xpander.ai
security: []
paths:
  /v1/agents/{agent_id}:
    get:
      tags:
        - API v1
        - Agents
      summary: Get Agent
      description: >-
        Retrieve a specific AI agent in a simplified view (tools as one list, no
        low-level graph/oas).
      operationId: Get_Agent_v1_agents__agent_id__get
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimplifiedAIAgent'
              example:
                id: a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5
                name: Research Assistant
                description: Searches the web and reports findings as JSON.
                icon: 🚀
                status: ACTIVE
                organization_id: 0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e
                deployment_type: serverless
                model_provider: anthropic
                model_name: claude-sonnet-5
                type: manager
                created_at: '2026-07-28T20:55:54.042725Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    SimplifiedAIAgent:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: Agent id.
        name:
          type: string
          title: Name
          description: Agent name.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Agent description.
        icon:
          anyOf:
            - type: string
            - type: 'null'
          title: Icon
          description: Agent icon.
        type:
          anyOf:
            - $ref: '#/components/schemas/AgentType'
            - type: 'null'
          description: Agent type.
        status:
          anyOf:
            - $ref: '#/components/schemas/AgentStatus'
            - type: 'null'
          description: Agent status.
        model_provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Provider
          description: LLM provider.
        model_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Name
          description: LLM model.
        framework:
          anyOf:
            - type: string
            - type: 'null'
          title: Framework
          description: >-
            Runtime: agno (built-in) or external-harness (Claude Code / Codex /
            OpenCode).
        deployment_type:
          anyOf:
            - $ref: '#/components/schemas/AIAgentDeploymentType'
            - type: 'null'
          description: serverless or container.
        harness_settings:
          anyOf:
            - $ref: '#/components/schemas/HarnessSettings'
            - type: 'null'
          description: >-
            External harness settings (default CLI, per-CLI models, permission
            mode, per-turn resources ceilings); absent for built-in agents.
        instructions:
          anyOf:
            - $ref: '#/components/schemas/AIAgentInstructions'
            - type: 'null'
          description: Agent instructions.
        knowledge_base_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Knowledge Base Ids
          description: Attached knowledge base ids.
          default: []
        source_node_types:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Source Node Types
          description: Trigger source types (sdk, webhook, slack, ...).
          default: []
        tools:
          items:
            $ref: '#/components/schemas/AgentTool'
          type: array
          title: Tools
          description: Tools attached to this agent.
          default: []
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
          description: Creation timestamp.
        created_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By
          description: Creator user id.
        created_by_details:
          anyOf:
            - $ref: '#/components/schemas/CreatedByDetails'
            - type: 'null'
          description: Creator details.
      type: object
      required:
        - name
      title: SimplifiedAIAgent
      description: >-
        Lean agent view exposing tools as one simple list, hiding low-level
        graph/oas internals.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentType:
      type: string
      enum:
        - manager
        - regular
        - a2a
        - curl
        - orchestration
      title: AgentType
      description: |-
        Enumeration of the agent types.

        Attributes:
            Manager: marks the agent as a Managing agent.
            Regular: marks the agent as a regular agent.
            A2A: marks the agent as an external agent used via A2A protocol.
            Curl: marks the agent as an external agent used via a CURL.
            Orchestration: marks the agent as an Orchestration object.
    AgentStatus:
      type: string
      enum:
        - DRAFT
        - ACTIVE
        - INACTIVE
      title: AgentStatus
      description: |-
        Enumeration of possible agent statuses.

        Attributes:
            DRAFT: Agent is in a draft state.
            ACTIVE: Agent is active and operational.
            INACTIVE: Agent is inactive and not operational.
    AIAgentDeploymentType:
      type: string
      enum:
        - serverless
        - container
      title: AIAgentDeploymentType
    HarnessSettings:
      properties:
        permission_mode:
          anyOf:
            - $ref: '#/components/schemas/HarnessPermissionMode'
            - type: 'null'
          default: full
        max_concurrent_tasks:
          anyOf:
            - type: integer
              minimum: 1
              maximum: 64
            - type: 'null'
          title: Max Concurrent Tasks
          default: 12
        workdir_gc_days:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Workdir Gc Days
          default: 14
          description: Days an idle working directory is kept.
        image_tag:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Tag
          description: >-
            Pinned build of the platform harness image; null means the current
            build.
        approval_hold_hours:
          anyOf:
            - type: integer
              minimum: 1
              maximum: 72
            - type: 'null'
          title: Approval Hold Hours
          default: 4
          description: Hours a turn waits for an approval before giving up.
        cli_auto_update:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Cli Auto Update
          default: true
          description: Platform-managed; always reads back true.
        default_cli:
          anyOf:
            - $ref: '#/components/schemas/HarnessCli'
            - type: 'null'
          description: CLI that runs the agent's turns. A new agent gets 'claude-code'.
        models:
          additionalProperties:
            type: string
          type: object
          title: Models
          default: {}
          description: >-
            One model per CLI, keyed by CLI name, e.g. {"claude-code":
            "claude-sonnet-5"}. A missing key means the platform default for
            that CLI.
        available_clis:
          items:
            $ref: '#/components/schemas/HarnessCli'
          type: array
          title: Available Clis
          default: []
          description: CLIs the agent's runtime reports as installed; read-only.
        runtime:
          anyOf:
            - $ref: '#/components/schemas/HarnessRuntime'
            - type: 'null'
          description: '''fleet'' for new agents; ''legacy'' keeps one pod per agent.'
        resources:
          anyOf:
            - $ref: '#/components/schemas/HarnessResources'
            - type: 'null'
      type: object
      title: HarnessSettings
      description: >-
        Runtime settings for an agent whose framework is 'external-harness';
        null for 'agno' agents.
    AIAgentInstructions:
      properties:
        role:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role
          default: []
        goal:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Goal
          default: []
        general:
          anyOf:
            - type: string
            - type: 'null'
          title: General
          default: ''
      type: object
      title: AIAgentInstructions
    AgentTool:
      properties:
        id:
          type: string
          title: Id
          description: >-
            Stable handle for this attached tool. Pass it to DELETE to remove
            the tool.
        type:
          $ref: '#/components/schemas/AgentToolType'
          description: The kind of attached tool.
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Human-readable tool name.
        connection_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Connection Id
          description: Connector connection id. Actions only.
        operation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Operation Id
          description: Operation catalog id. Actions only.
        operation_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Operation Name
          description: OpenAPI operationId. Actions only.
        use_mock:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Use Mock
          description: >-
            Operation serves AI-generated mock data instead of the real API.
            Actions only.
        custom_function_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Custom Function Id
          description: Custom function id. Custom functions only.
        mcp_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Id
          description: MCP registry id. MCP only.
        allowed_tools:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Allowed Tools
          description: Subset of MCP tools exposed. MCP only.
        mcp_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Url
          description: MCP server url. MCP only.
        mcp_auth_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Auth Type
          description: MCP auth type (api_key/oauth2/custom_headers/none). MCP only.
        mcp_registry_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Registry Id
          description: >-
            Registry entry id when this MCP is attached from the shared org
            registry (editing it affects every agent). Absent for inline MCPs.
            MCP only.
        mcp_transport:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Transport
          description: MCP transport (streamable-http/sse/stdio). MCP only.
        mcp_headers:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Mcp Headers
          description: >-
            Custom header names configured on the MCP (keys only; values are
            never returned). MCP only.
        mcp_client_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Client Id
          description: OAuth2 client id for the MCP, if set. MCP only.
        mcp_additional_scopes:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Mcp Additional Scopes
          description: Extra OAuth2 scopes for the MCP. MCP only.
        mcp_share_user_token:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Mcp Share User Token
          description: >-
            Whether the authorized MCP token is shared across the org's other
            agents. MCP only.
        mcp_has_api_key:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Mcp Has Api Key
          description: >-
            Whether an API key is stored for the MCP (the value is never
            returned). MCP only.
        mcp_has_client_secret:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Mcp Has Client Secret
          description: >-
            Whether an OAuth2 client secret is stored for the MCP (the value is
            never returned). MCP only.
        target_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Target Id
          description: Referenced sub-agent or workflow id.
        skill_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Skill Name
          description: Skill name from the xpander skills catalog. Skills only.
      type: object
      required:
        - id
        - type
      title: AgentTool
      description: >-
        A tool attached to an agent — the simplified, unified view of one graph
        entry.
    CreatedByDetails:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        email:
          type: string
          title: Email
      type: object
      required:
        - id
        - name
        - email
      title: CreatedByDetails
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    HarnessPermissionMode:
      type: string
      enum:
        - full
        - gated
      title: HarnessPermissionMode
      description: >-
        Permission mode for an external-harness agent's workspace commands.
        'full' runs them; 'gated' holds the ones matched by gated_commands for
        approval.
    HarnessCli:
      type: string
      enum:
        - claude-code
        - codex
        - opencode
        - xpander
      title: HarnessCli
      description: A CLI the harness container can run.
    HarnessRuntime:
      type: string
      enum:
        - fleet
        - legacy
      title: HarnessRuntime
      description: >-
        Where a harness agent's turns run: the shared executor fleet ('fleet',
        the default for new agents) or one always-on pod per agent ('legacy').
    HarnessResources:
      properties:
        memory_limit:
          anyOf:
            - type: string
            - type: 'null'
          title: Memory Limit
          description: >-
            Memory ceiling per turn, e.g. '24Gi', '512Mi' or a byte count (128Mi
            to 24Gi).
        memory_high:
          anyOf:
            - type: string
            - type: 'null'
          title: Memory High
          description: >-
            Throttle threshold below memory_limit; set together with
            memory_limit.
        cpu:
          anyOf:
            - type: number
              minimum: 0.1
              maximum: 8
            - type: 'null'
          title: Cpu
          description: CPU cores per turn (0.1 to 8; '500m' is accepted).
        pids:
          anyOf:
            - type: integer
              minimum: 64
              maximum: 8192
            - type: 'null'
          title: Pids
          description: Process limit per turn (64 to 8192).
        disk:
          anyOf:
            - type: string
            - type: 'null'
          title: Disk
          description: Disk ceiling per turn, e.g. '10Gi' (1Gi to 50Gi).
      additionalProperties: false
      type: object
      title: HarnessResources
      description: >-
        Per-turn sandbox ceilings for a harness agent on the fleet; every unset
        field keeps the runner default. A value past the platform caps is
        rejected with 422.
    AgentToolType:
      type: string
      enum:
        - action
        - custom_function
        - mcp
        - agent
        - workflow
        - skill
      title: AgentToolType
      description: Type of a tool attached to an agent.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: API Key for authentication
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.