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

# Agents.External SDK Reference

> SDK reference for the Agents.External API, available in Node.js and Python.

## Agents.External

### List External

Returns the external A2A agents visible to the caller, ordered newest first.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.external.list()

    # Handle response
    print(res)

```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.agents.external.list();

  console.log(result);
}

run();
```

**Parameters**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "limit": Optional[int],
    "starting_after": Optional[str],
    "ending_before": Optional[str],
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  limit?: number;
  startingAfter?: string;
  endingBefore?: string;
}
```

**Response**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "object": Optional[str],
    "data": [{  # optional
        "agent_id": str,
        "key": str,
        "display_name": str,
        "description": str,
        "path": str,
        "project_id": str,
        "agent_url": str,
        "card_url": Optional[str],
        "headers": Dict[str, ExternalAgentHeader],
        "protocol_version": str,
        "preferred_transport": str,
        "cached_card": Dict[str, Any],
        "card_refreshed_at": str,  # optional
        "created_at": str,
        "updated_at": str,
        "created_by_id": str,
        "updated_by_id": str,
        "version": str,
    }],
    "has_more": Optional[bool],
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  object?: string;
  data?: {
    agentId: string;
    key: string;
    displayName: string;
    description: string;
    path: string;
    projectId: string;
    agentUrl: string;
    cardUrl?: string;
    headers: Record<string, ExternalAgentHeader>;
    protocolVersion: string;
    preferredTransport: string;
    cachedCard: Record<string, unknown>;
    cardRefreshedAt?: Date;
    createdAt: Date;
    updatedAt: Date;
    createdById: string;
    updatedById: string;
    version: string;
  }[];
  hasMore?: boolean;
}
```

### Create an External

Registers an external A2A agent after securely fetching and validating its agent card.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.external.create(key="<key>", display_name="Support triage agent", path="Default/agents", agent_url="https://agent.example.com/a2a")

    # Handle response
    print(res)

```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.agents.external.create({
    key: "<key>",
    displayName: "Support triage agent",
    path: "Default/agents",
    agentUrl: "https://agent.example.com/a2a",
  });

  console.log(result);
}

run();
```

**Parameters**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "key": str,  # required
    "display_name": str,  # required
    "path": str,  # required
    "agent_url": str,  # required
    "description": Optional[str],
    "project_id": Optional[str],
    "card_url": Optional[str],
    "headers": Dict[str, ExternalAgentHeader],  # optional
    "protocol_version": Optional[str],
    "preferred_transport": Optional[str],
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  key: string;  // required
  displayName: string;  // required
  description?: string;
  path: string;  // required
  projectId?: string;
  agentUrl: string;  // required
  cardUrl?: string;
  headers?: Record<string, ExternalAgentHeader>;
  protocolVersion?: string;
  preferredTransport?: string;
}
```

**Response**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "agent": {  # optional
        "agent_id": str,
        "key": str,
        "display_name": str,
        "description": str,
        "path": str,
        "project_id": str,
        "agent_url": str,
        "card_url": Optional[str],
        "headers": Dict[str, ExternalAgentHeader],
        "protocol_version": str,
        "preferred_transport": str,
        "cached_card": Dict[str, Any],
        "card_refreshed_at": str,  # optional
        "created_at": str,
        "updated_at": str,
        "created_by_id": str,
        "updated_by_id": str,
        "version": str,
    },
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  agent?: {
    agentId: string;
    key: string;
    displayName: string;
    description: string;
    path: string;
    projectId: string;
    agentUrl: string;
    cardUrl?: string;
    headers: Record<string, ExternalAgentHeader>;
    protocolVersion: string;
    preferredTransport: string;
    cachedCard: Record<string, unknown>;
    cardRefreshedAt?: Date;
    createdAt: Date;
    updatedAt: Date;
    createdById: string;
    updatedById: string;
    version: string;
  };
}
```

### Retrieve an External

Retrieves a registered external A2A agent by key or ID. Encrypted header values are always masked.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.external.retrieve(agent_key="<value>")

    # Handle response
    print(res)

```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.agents.external.retrieve({
    agentKey: "<value>",
  });

  console.log(result);
}

run();
```

**Parameters**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "agent_key": str,  # required
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  agentKey: string;  // required
}
```

**Response**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "agent": {  # optional
        "agent_id": str,
        "key": str,
        "display_name": str,
        "description": str,
        "path": str,
        "project_id": str,
        "agent_url": str,
        "card_url": Optional[str],
        "headers": Dict[str, ExternalAgentHeader],
        "protocol_version": str,
        "preferred_transport": str,
        "cached_card": Dict[str, Any],
        "card_refreshed_at": str,  # optional
        "created_at": str,
        "updated_at": str,
        "created_by_id": str,
        "updated_by_id": str,
        "version": str,
    },
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  agent?: {
    agentId: string;
    key: string;
    displayName: string;
    description: string;
    path: string;
    projectId: string;
    agentUrl: string;
    cardUrl?: string;
    headers: Record<string, ExternalAgentHeader>;
    protocolVersion: string;
    preferredTransport: string;
    cachedCard: Record<string, unknown>;
    cardRefreshedAt?: Date;
    createdAt: Date;
    updatedAt: Date;
    createdById: string;
    updatedById: string;
    version: string;
  };
}
```

### Delete an External

Deletes a registered external A2A agent.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.external.delete(agent_key="<value>")

    # Handle response
    print(res)

```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.agents.external.delete({
    agentKey: "<value>",
  });

  console.log(result);
}

run();
```

**Parameters**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "agent_key": str,  # required
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  agentKey: string;  // required
}
```

### Update an External

Updates mutable registry and A2A connection fields. An empty encrypted header value preserves the stored secret.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.external.update(agent_key="<value>")

    # Handle response
    print(res)

```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.agents.external.update({
    agentKey: "<value>",
    updateExternalAgentRequest: {},
  });

  console.log(result);
}

run();
```

**Parameters**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "agent_key": str,  # required
    "display_name": Optional[str],
    "description": Optional[str],
    "path": Optional[str],
    "project_id": Optional[str],
    "agent_url": Optional[str],
    "card_url": Optional[str],
    "headers": Dict[str, ExternalAgentHeader],  # optional
    "protocol_version": Optional[str],
    "preferred_transport": Optional[str],
    "clear_headers": Optional[bool],
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  agentKey: string;  // required
  updateExternalAgentRequest: {  // required
    displayName?: string;
    description?: string;
    path?: string;
    projectId?: string;
    agentUrl?: string;
    cardUrl?: string;
    headers?: Record<string, ExternalAgentHeader>;
    protocolVersion?: string;
    preferredTransport?: string;
    clearHeaders?: boolean;
  };
}
```

**Response**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "agent": {  # optional
        "agent_id": str,
        "key": str,
        "display_name": str,
        "description": str,
        "path": str,
        "project_id": str,
        "agent_url": str,
        "card_url": Optional[str],
        "headers": Dict[str, ExternalAgentHeader],
        "protocol_version": str,
        "preferred_transport": str,
        "cached_card": Dict[str, Any],
        "card_refreshed_at": str,  # optional
        "created_at": str,
        "updated_at": str,
        "created_by_id": str,
        "updated_by_id": str,
        "version": str,
    },
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  agent?: {
    agentId: string;
    key: string;
    displayName: string;
    description: string;
    path: string;
    projectId: string;
    agentUrl: string;
    cardUrl?: string;
    headers: Record<string, ExternalAgentHeader>;
    protocolVersion: string;
    preferredTransport: string;
    cachedCard: Record<string, unknown>;
    cardRefreshedAt?: Date;
    createdAt: Date;
    updatedAt: Date;
    createdById: string;
    updatedById: string;
    version: string;
  };
}
```

### Refresh Card

Securely fetches the current agent card and replaces the cached card metadata.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.external.refresh_card(agent_key="<value>", refresh_external_agent_card_request={})

    # Handle response
    print(res)

```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.agents.external.refreshCard({
    agentKey: "<value>",
    refreshExternalAgentCardRequest: {},
  });

  console.log(result);
}

run();
```

**Parameters**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "agent_key": str,  # required
    "refresh_external_agent_card_request": Dict[str, Any],  # required
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  agentKey: string;  // required
  refreshExternalAgentCardRequest: Record<string, unknown>;  // required
}
```

**Response**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "agent": {  # optional
        "agent_id": str,
        "key": str,
        "display_name": str,
        "description": str,
        "path": str,
        "project_id": str,
        "agent_url": str,
        "card_url": Optional[str],
        "headers": Dict[str, ExternalAgentHeader],
        "protocol_version": str,
        "preferred_transport": str,
        "cached_card": Dict[str, Any],
        "card_refreshed_at": str,  # optional
        "created_at": str,
        "updated_at": str,
        "created_by_id": str,
        "updated_by_id": str,
        "version": str,
    },
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  agent?: {
    agentId: string;
    key: string;
    displayName: string;
    description: string;
    path: string;
    projectId: string;
    agentUrl: string;
    cardUrl?: string;
    headers: Record<string, ExternalAgentHeader>;
    protocolVersion: string;
    preferredTransport: string;
    cachedCard: Record<string, unknown>;
    cardRefreshedAt?: Date;
    createdAt: Date;
    updatedAt: Date;
    createdById: string;
    updatedById: string;
    version: string;
  };
}
```

### Test Connection

Validates the stored connection configuration and securely fetches the external agent card without persisting changes.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.external.test_connection(agent_key="<value>", test_external_agent_connection_request={})

    # Handle response
    print(res)

```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.agents.external.testConnection({
    agentKey: "<value>",
    testExternalAgentConnectionRequest: {},
  });

  console.log(result);
}

run();
```

**Parameters**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "agent_key": str,  # required
    "test_external_agent_connection_request": Dict[str, Any],  # required
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  agentKey: string;  // required
  testExternalAgentConnectionRequest: Record<string, unknown>;  // required
}
```

**Response**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "reachable": Optional[bool],
    "card": Dict[str, Any],  # optional
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  reachable?: boolean;
  card?: Record<string, unknown>;
}
```


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