Foundry worker vs. agent worker（Foundry Worker 与 Agent Worker）

:::callout{theme="warning" title="Legacy"} Agent worker is in the legacy phase of development. Foundry worker is the recommended way to run all data connection sources. This page explains why, and answers common questions about moving off agent worker. :::

Context

Agent worker was the original way Data Connection sources ran in Foundry: capabilities executed on a customer-managed agent host inside the customer network. Foundry worker is the recommended option for all sources today: capabilities run in Foundry's containerized, scalable job execution environment. Agents now act only as network proxies via agent proxy egress policies; they no longer execute capabilities.

See architecture diagrams for how each connection type fits together, and core concepts for definitions.

Benefits of Foundry worker

Scalability and isolation

Foundry worker runs each capability in its own container, sized to the job. Jobs no longer compete for the agent's shared JVM heap, and a long-running sync no longer blocks short jobs from running in parallel. Compute scales independently per job, rather than being bounded by the capacity of a single agent host.

Stability and release cadence

Foundry worker runs in Foundry's managed compute environment and is updated continuously alongside the rest of the platform. Agent worker runs on customer-managed hosts and can only upgrade during the agent's maintenance window, typically once a week. Bug fixes and improvements therefore take longer to reach the agent. Agent worker is also exposed to host-level issues (resource exhaustion, OS or JVM problems, scheduled downtime); see agent troubleshooting for the common failure modes. Foundry worker avoids these by removing the customer-managed runtime from the path.

Access to all capabilities and new development

Virtual tables, virtual media, using sources in code from external transforms, external functions and compute modules, and several capabilities added in recent years do not run on agent worker. New capabilities and ongoing feature development target Foundry worker only.

Lower operational burden

Foundry worker removes the need to tune the agent JVM heap, plan agent host capacity, and monitor the agent process at the OS level. When agents remain in the picture, they act only as a network proxy via agent proxy — a much smaller operational footprint than running compute on the agent.

Cleaner credential lifecycle

Foundry manages source credentials centrally instead of tying them to a specific agent. Reassigning agents to a source no longer requires re-entering secrets. Re-provisioning an agent host does not invalidate credentials.

Common questions

Is Foundry worker as secure as agent worker?

Yes. Foundry stores source credentials encrypted at rest and in transit in both models. The only material difference is where the encryption key for source credentials lives: on disk on the agent host (agent worker) or securely managed inside Foundry (Foundry worker). With agent proxy, network connectivity to your source systems remains outbound-only, initiated from the agent inside your network. This matches the agent worker model.

Is Foundry worker as performant as agent worker?

Yes. Containerized jobs do not compete for a single agent's heap and can scale per job.

Does this change my network connectivity model?

No. With agent proxy, the agent still initiates an outbound WebSocket to Foundry, and all traffic to your source systems still originates from the agent inside your network — no new inbound paths into your network, same model as agent worker. What moves is where capabilities execute, not how Foundry reaches your systems.

What happens to my existing agent worker sources?

Existing agent worker sources will continue to work. Agent worker is legacy, fully supported. When you are ready, migrate using the guided wizard. Note that this migration is reversible for 30 days.

What about agent proxy?

:::callout{theme="neutral"} Agent proxy is not the same as agent worker. Agent proxy is a networking mode for Foundry worker, not a worker type. If "agent" appears in a discussion about a new source, agent proxy is almost always what is meant. See architecture for the architecture diagrams. :::

Switch source from agent worker to Foundry worker

Most agent-based sources should be migrated to a Foundry worker, either a direct connection for systems accessible from Foundry, or an agent-proxy connection for sources hosted on separate networks.

:::callout{theme="neutral"} If you encounter any issues migrating from agent worker to Foundry worker, you may revert to your previous connection settings within 30 days. :::

Prerequisites

Before starting the migration, ensure the following:

• You have at least one healthy agent assigned to the source that can supply source secrets, certificates, and, if applicable, JDBC drivers.
• You have the required permissions to create egress policies. To create new egress policies, you must have access to the workflow titled Manage network egress configuration in Control Panel, which is granted to the Information Security Officer role.

Migration steps

To perform a migration to a Foundry worker, follow the steps below:

1. Navigate to Connection settings > Connection details and select Compute: Agent worker. This opens a dialog where you can select Migrate to Foundry worker.

1. Review the migration overview. The walkthrough dialog explains the steps involved and confirms that the process is reversible. Select Continue to proceed.

1. Choose a representative agent. Select a healthy agent currently assigned to the source. The selected agent is used to copy secrets and certificates to Foundry and to suggest required egress configuration based on the agent's current setup. You must acknowledge that secrets on the selected agent will be saved to Foundry.

1. Copy certificates to the source. With Foundry worker, certificates must be applied directly to the source rather than to the agent. Select the certificates from the representative agent that should be transferred to your data source. If no certificates are found on the agent, you can skip this step.

1. (Optional) Configure a JDBC driver if required by the source type. Select a driver from the representative agent to use with the Foundry worker.

1. Add egress policies. Configure direct connection or agent proxy egress policies to define how the Foundry worker should reach your source systems.

1. Review the confirmation step. Before completing the migration, acknowledge the following:

2. All running jobs (syncs, exports, tasks) will be terminated as part of the migration. Scheduled jobs will run in Foundry on the next scheduled run, but unscheduled jobs must be manually restarted.

3. You have 30 days to revert to your previous configuration, if necessary.

Select Migrate to complete the process.

Switch manually

If you prefer not to use the guided migration wizard, you can select Switch to Foundry worker manually from the migration dialog. Note that when switching manually, credentials must be re-entered, as the automated secret transfer from the agent is not performed.

Revert to agent worker

For 30 days after a migration, you can revert the source to its previous agent worker configuration:

1. Navigate to Connection settings > Connection details on the migrated source.
2. In the Compute dropdown, select Agent worker > Revert.
3. In the Revert source to Agent worker dialog, acknowledge that:
4. All connection settings, including credentials, will be reverted to the state before migration. Any changes made since will be lost.
5. Unscheduled jobs (syncs, exports, tasks) will need to be restarted manually. Scheduled jobs will use the pre-migration connection settings on their next scheduled run. Jobs that started successfully after the migration continue running with migrated settings until completion.
6. Select Revert migration to confirm.

If you prefer to reconfigure the source on agent worker manually rather than restoring the pre-migration settings, select Switch to connect via Agent worker manually from the dialog.

Troubleshooting

This section describes situations that may occur during the migration, as well as suggested resolution steps. As a reminder, the migration is reversible for 30 days.

Could not resolve type id as a subtype of 'com.palantir.magritte.api.Source'

Suggested resolution:

• This happens when a dependency required for the source cannot be found. Ensure that you have configured all required certificates, proxies, and drivers required for a particular source, then retry the migration.

UnknownHostException

Suggested resolution:

• Ensure that correct egress policies are assigned to the source.
• Confirm that Foundry is able to access the endpoint that is throwing the exception.

Driver class not found

Suggested resolution:

• Confirm that the correct driver is uploaded to the JDBC source.

PKIX path building failed

Suggested resolution:

• Ensure that correct certificates are added to the source.

---

中文翻译

Foundry Worker 与 Agent Worker

:::callout{theme="warning" title="已弃用(Legacy)"} Agent Worker 已进入开发周期的已弃用阶段。Foundry Worker 是运行所有数据连接源的推荐方式。本页面将解释原因，并解答关于从 Agent Worker 迁移的常见问题。 :::

背景(Background)

Agent Worker 是 Data Connection 源在 Foundry 中运行的原始方式：能力(capabilities)在客户网络内的客户管理代理(agent)主机上执行。Foundry Worker 是目前所有源的推荐选项：能力在 Foundry 容器化、可扩展的作业执行环境中运行。代理现在仅通过代理出口策略(agent proxy egress policies)充当网络代理，不再执行能力。

请参阅架构图了解每种连接类型的组合方式，以及核心概念了解相关定义。

Foundry Worker 的优势

可扩展性与隔离性(Scalability and isolation)

Foundry Worker 在独立的容器中运行每个能力，容器大小根据作业需求调整。作业不再争夺代理的共享 JVM 堆内存，长时间运行的同步不再阻塞短作业并行执行。计算资源按作业独立扩展，而非受限于单个代理主机的容量。

稳定性与发布节奏(Stability and release cadence)

Foundry Worker 在 Foundry 的托管计算环境中运行，并随平台其他部分持续更新。Agent Worker 在客户管理的主机上运行，只能在代理的维护窗口（通常每周一次）期间升级。因此，错误修复和改进需要更长时间才能到达代理。Agent Worker 还面临主机级别的问题（资源耗尽、操作系统或 JVM 问题、计划停机）；常见故障模式请参见代理故障排除。Foundry Worker 通过移除路径中的客户管理运行时来避免这些问题。

访问所有能力与新功能(Access to all capabilities and new development)

虚拟表(Virtual tables)、虚拟媒体(Virtual media)、通过外部转换(external transforms)在代码中使用源、外部函数(external functions)和计算模块(compute modules)，以及近年来添加的若干能力，均不在 Agent Worker 上运行。新能力和持续的功能开发仅针对 Foundry Worker。

更低的运维负担(Lower operational burden)

Foundry Worker 消除了调整代理 JVM 堆内存、规划代理主机容量以及在操作系统级别监控代理进程的需求。当代理仍然存在时，它们仅通过代理代理(agent proxy)充当网络代理——其运维规模远小于在代理上运行计算。

更清晰的凭证生命周期(Cleaner credential lifecycle)

Foundry 集中管理源凭证，而非将其绑定到特定代理。将代理重新分配给源不再需要重新输入密钥。重新配置代理主机不会使凭证失效。

常见问题

Foundry Worker 和 Agent Worker 一样安全吗？

是的。在两种模型中，Foundry 都以加密方式存储源凭证（静态存储和传输中）。唯一的实质性区别在于源凭证加密密钥的存储位置：在代理主机的磁盘上（Agent Worker）或在 Foundry 内部安全管理（Foundry Worker）。通过代理代理(agent proxy)，到源系统的网络连接仍然是仅出站的，由网络内部的代理发起。这与 Agent Worker 模型一致。

Foundry Worker 和 Agent Worker 性能一样好吗？

是的。容器化作业不会争夺单个代理的堆内存，并且可以按作业扩展。

这会改变我的网络连接模型吗？

不会。通过代理代理(agent proxy)，代理仍然向 Foundry 发起出站 WebSocket 连接，所有到源系统的流量仍然来自网络内部的代理——不会为您的网络引入新的入站路径，与 Agent Worker 模型相同。发生变化的是能力在何处执行，而非Foundry 如何访问您的系统。

我现有的 Agent Worker 源会怎样？

现有的 Agent Worker 源将继续工作。Agent Worker 是已弃用但完全受支持的。当您准备好时，可以使用引导式向导进行迁移。请注意，此迁移在 30 天内可逆。

代理代理(Agent Proxy)呢？

:::callout{theme="neutral"} 代理代理(Agent proxy)与 Agent Worker 不同。 代理代理是 Foundry Worker 的一种网络模式，而非工作节点类型。如果在关于新源的讨论中出现"代理(agent)"，几乎总是指代理代理。请参阅架构了解架构图。 :::

将源从 Agent Worker 切换到 Foundry Worker

大多数基于代理的源应迁移到 Foundry Worker，对于可从 Foundry 访问的系统使用直接连接(direct connection)，对于托管在独立网络上的源使用代理代理连接(agent-proxy connection)。

:::callout{theme="neutral"} 如果在从 Agent Worker 迁移到 Foundry Worker 时遇到任何问题，您可以在 30 天内恢复到之前的连接设置。 :::

前提条件(Prerequisites)

在开始迁移之前，请确保满足以下条件：

• 您至少有一个健康的代理分配给该源，能够提供源密钥、证书，以及（如果适用）JDBC 驱动程序。
• 您拥有创建出口策略所需的权限。要创建新的出口策略，您必须有权访问控制面板(Control Panel)中名为Manage network egress configuration的工作流，该权限授予信息安全官(Information Security Officer)角色。

迁移步骤(Migration steps)

要执行到 Foundry Worker 的迁移，请按照以下步骤操作：

1. 导航至连接设置(Connection settings) > 连接详情(Connection details)，选择计算：Agent Worker(Compute: Agent worker)。这将打开一个对话框，您可以在其中选择迁移到 Foundry Worker(Migrate to Foundry worker)。

1. 查看迁移概览。向导对话框说明了涉及的步骤，并确认该过程是可逆的。选择继续(Continue)以继续。

1. 选择一个代表性代理。选择当前分配给该源的健康代理。所选代理用于将密钥和证书复制到 Foundry，并根据代理的当前设置建议所需的出口配置。您必须确认所选代理上的密钥将保存到 Foundry。

1. 将证书复制到源。使用 Foundry Worker 时，证书必须直接应用于源，而非代理。从代表性代理中选择应传输到数据源的证书。如果在代理上未找到证书，您可以跳过此步骤。

1. （可选）如果源类型需要，配置 JDBC 驱动程序。从代表性代理中选择一个驱动程序以与 Foundry Worker 一起使用。

1. 添加出口策略。配置直接连接(direct connection)或代理代理(agent proxy)出口策略，以定义 Foundry Worker 应如何访问您的源系统。

1. 查看确认步骤。在完成迁移之前，请确认以下事项：

2. 所有正在运行的作业（同步、导出、任务）将在迁移过程中终止。计划作业将在下次计划运行时在 Foundry 中运行，但未计划作业必须手动重新启动。

3. 如有必要，您有 30 天时间恢复到之前的配置。

选择迁移(Migrate)以完成该过程。

手动切换(Switch manually)

如果您不希望使用引导式迁移向导，可以从迁移对话框中选择手动切换到 Foundry Worker(Switch to Foundry worker manually)。请注意，手动切换时，必须重新输入凭证，因为不会执行从代理自动传输密钥的操作。

恢复到 Agent Worker(Revert to agent worker)

迁移后的 30 天内，您可以将源恢复到之前的 Agent Worker 配置：

1. 在已迁移的源上，导航至连接设置(Connection settings) > 连接详情(Connection details)。
2. 在计算(Compute)下拉菜单中，选择Agent Worker > 恢复(Revert)。
3. 在将源恢复到 Agent Worker(Revert source to Agent worker)对话框中，确认以下事项：
4. 所有连接设置（包括凭证）将恢复到迁移前的状态。此后所做的任何更改都将丢失。
5. 未计划的作业（同步、导出、任务）需要手动重新启动。计划作业将在下次计划运行时使用迁移前的连接设置。迁移后成功启动的作业将继续使用迁移后的设置运行，直至完成。
6. 选择恢复迁移(Revert migration)以确认。

如果您希望手动在 Agent Worker 上重新配置源，而非恢复迁移前的设置，请从对话框中选择手动切换到通过 Agent Worker 连接(Switch to connect via Agent worker manually)。

故障排除(Troubleshooting)

本节描述迁移过程中可能发生的情况以及建议的解决步骤。提醒一下，迁移在 30 天内是可逆的。

Could not resolve type id as a subtype of 'com.palantir.magritte.api.Source'

建议解决方案：

• 当找不到源所需的依赖项时会发生此情况。请确保已配置特定源所需的所有证书、代理和驱动程序，然后重试迁移。

UnknownHostException

建议解决方案：

• 确保已为源分配正确的出口策略。
• 确认 Foundry 能够访问抛出异常的服务端点。

Driver class not found

建议解决方案：

• 确认已将正确的驱动程序上传到 JDBC 源。

PKIX path building failed

建议解决方案：

• 确保已将正确的证书添加到源。