PCC Agent

PCC Agent executes application-specific workflows on proxy nodes, coordinating tool invocations across PCC nodes.

Overview

PCCAgentApp is a PCC cloud application that executes use-case-specific workflows, each defined in its own framework. Because PCCAgentApp is a cloud app, it inherits the same properties as all PCC node software, including sandboxing, Per-request isolation, and entitlements that govern data flow between system processes. PCCAgentApp integrates with PCC’s Transitive Trust and runs on a proxy node as one of PCC’s PCC cloud applications; a proxy node running PCC Agent is an agent node. The agent node calls out to worker nodes as needed to orchestrate the workflow.

PCC Agent workflows

Each workflow is identified by request-routing parameters specified in the client-initiated request, combined with the service name pcc-agent. The Node selection routes these requests to PCCAgentApp.

Upon receiving a request, PCCAgentApp locates the corresponding workflow through a lookup against a table compiled into the PCCAgentApp binary. The workflow is then invoked within the per-request address space of PCCAgentApp.

The workflow receives input and output data streams brokered by CloudBoard through a request-handler function onRequest. A Toolbox object is also provided, giving the workflow access to capabilities such as LLM inference on Apple Silicon Stateless Inference or Google Cloud Stateless Inference, Private Information Retrieval lookups, and external tool calls to access world knowledge.

The agent workflows and features provided by PCC Agent include:

Multi-Turn Agent: Handles conversational and tool-calling interactions over a persistent connection, where a single client interaction produces a sequence of related turns and the model’s intermediate state can be reused across turns.
Visual Lookup: Identifies visual entities from a client-supplied image embedding, searching the entity database using Private Information Retrieval to return candidate entities with resolved metadata.
Embedding Agent: Turns text and decoded video frames supplied by a caller into embedding vectors, exposing Embedding Generation directly as a workflow without additional processing.
Workout Buddy: Delivers motivation based on a user’s fitness history during workouts, implemented by FitnessIntelligenceAgent, which supports requests originating directly from Apple Watch. Its input is a chat-style transcript, and depending on the user’s voice configuration, the workflow may return streamed LLM text tokens, synthesized audio (using Speech Synthesis), or both.
HomeKit Secure Video Analysis: Analyzes HomeKit Secure Video clips on behalf of a user’s home, producing video descriptions and embeddings.
Visual Generation: Runs the Apple Diffusion Model to produce images for on-device features, pairing the diffusion pipeline with content-safety guardrail models and the shared Media Decoding worker.

Extending workflows with tools

Agentic workflows enable powerful features by calling tools to accomplish a task. The workflow makes some of these calls itself; the model requests others during inference. When the model requests a tool that PCC Agent doesn’t implement, PCCAgentApp returns the request to the user’s device to execute locally; the device then supplies the result in a subsequent turn. To avoid that round trip and keep request iteration fast, PCC Agent implements other tools directly.

For the tools it implements, PCC uses the most privacy-preserving mechanism available:

Within the trust boundary: Many tools can run entirely inside PCC, exposing nothing beyond what the request already does. The workflow runs such a tool directly, or issues a delegated tool call to another PCC node, for example, running model inference on an inference node, or offloading resource-intensive work to a worker node. For these in-boundary tools, query-derived data stays inside the High-security inference; this is the strongest privacy posture available for a tool.
Private Information Retrieval: Some queries against an external database can be issued using Private Information Retrieval. PIR uses homomorphic encryption to return the requested record without the server learning which one the query selected, so the lookup reveals nothing about the user’s request.
External tool call: Some capabilities, such as world knowledge, require information or services that can’t reside inside the trust boundary. To offer these capabilities, PCC Agent supports external tool calls through a dedicated tool gateway. Such calls necessarily send query-derived data outside the trust boundary, so they’re designed to offer the same level of privacy as that of on-device tool access: they contain no source-device or user identifier, only a fixed set of unencrypted routing metadata; every call is recorded in the Request execution log and surfaced in the Appendix: Apple Intelligence Report; and requests using external tool calls opt into additional Non-Targetability protections.

By preferring the first mechanism that can deliver a capability, PCC Agent keeps data inside the trust boundary by default and crosses that boundary only when delivering the experience requires it.

Delegated tool calls

When a workflow invokes a delegated tool, PCCAgentApp issues an outbound PCC request using makePCCRequest from the CloudBoardJob framework. Under Transitive Trust, CloudBoard validates the attestation of the node selected by the PCC Gateway to handle the invocation, and the Request execution log includes the attestations of every such node used within a workflow.

Which node handles a delegated tool depends on the tool. Model inference runs on a dedicated inference node. Many tools are handled by separate nodes running the PCCAgentWorker service, supported by an accompanying cloud application, PCCAgentWorkerApp.

The delegated tools that PCC Agent workflows invoke include:

Routing work to a dedicated worker node, rather than running it alongside the workflow on the agent node, serves two purposes:

Availability and concurrency: The user’s device may use a Application protocol when submitting a request to PCC, and the PCC Gateway attempts to route the request to the PCC node that corresponds to that attestation, reducing the need for an additional round trip. Offloading resource-intensive tool invocations to a worker node helps ensure that nodes with client-cached attestations remain available, maintaining a high degree of request concurrency.
Security isolation: Running a tool on a dedicated worker node, rather than alongside the workflow that orchestrates it, isolates that tool’s attack surface from other use cases. Exploitation of a vulnerability in one tool is confined to the worker node that runs it and to the request in flight, so it does not reach the data of the workflow that invoked it or of workloads on other nodes.

External tool calls

To issue an external tool call, PCCAgentApp submits the request to the tool gateway: a service that runs outside the PCC trust boundary and relays each call to a downstream tool provider. Routing all external calls through a single gateway lets PCC apply consistent constraints to data leaving its trust boundary: external requests are designed to carry no identifiable metadata, to preserve PCC’s Non-Targetability properties, and to remain transparent to the user.

The tool gateway implements a gRPC service through which PCC accesses external tool providers, translating between a gRPC transport and the tool-calling protocol provided by external services. On the PCC node, cb_bridged manages outbound network connectivity to the tool gateway. When a workflow invokes an external tool, the request flows from PCCAgentApp through its cb_jobhelper instance to cb_bridged, which opens a bidirectional gRPC stream to the tool gateway over a persistent channel.

The tool-calling protocol provided by the tool gateway is similar to the Model Context Protocol and provides a JSON-RPC-based format for tool calls. The tool gateway wraps these JSON-RPC messages within a lightweight Protobuf envelope for transport over gRPC. PCCAgentApp specifies the target tool server and tool directly; tool enumeration is not supported. For the gRPC service definition, message formats, and connection life-cycle details, see Appendix: Tool Gateway Protocol.

cb_bridged maintains a persistent connection to the tool gateway. For each external tool call, cb_bridged establishes a new bidirectional gRPC stream. A single PCC request may make several external tool calls, with each call getting an isolated stream.

Security properties of external tool calls

The tool gateway and any downstream tool providers operate outside the PCC trust boundary, and an external tool call necessarily carries query-derived data across that boundary. To preserve the same level of privacy as that of on-device tool access, external tool calls are designed to be non-identifiable and transparent. A third concern arises because query-derived content is visible outside the trust boundary: an attacker could use that content to steer subsequent processing of the request toward a compromised host.

PCC’s external tool calls address each of these concerns:

Non-identifiability: External tool calls travel without information that links them to a particular user or device, just as with device-originated requests issued through an OHTTP relay. Each call includes a fixed set of unencrypted routing metadata, such as the application and feature the request came from and the calling node’s software version, with no device or user identifier added.
Transparency: A proxy node records every external tool call it makes as its own entry in the Request execution log, capturing the tool invoked and the arguments sent. Those entries stream end-to-end encrypted to the user’s device, which collects them into the outboundCalls list of the request’s Apple Intelligence Report record, so the user can see exactly what data left the trust boundary for each call. A tool that the user’s device executes locally, by contrast, produces no outboundCalls entry; its request and result appear as ordinary prompt and response content in the log, like any other model input and output.
Non-targetability: A tool call’s contents are exposed to the tool gateway and to the downstream tool provider; an attacker who controlled either could potentially use what they observe to attempt to steer subsequent processing toward a compromised host. To prevent that, once a request has made an external tool call, it opts into Node selection for requests from proxy nodes for the selection of any further PCC nodes.

Responsible AI

PCC Agent enforces Apple’s Responsible AI principles on the server through several mechanisms that act on a request inside the trust boundary. Each is designed to preserve PCC’s transparency and non-targetability guarantees while constraining what a model may receive or return.

Safety overrides

PCC Agent supports a server-side safety override mechanism that lets us respond to a safety incident by rejecting request or response content that matches a set of regular-expression patterns. This approach mirrors the override mechanism that Apple Intelligence uses on a user’s device. Because the rules travel as data rather than code, we can deploy a mitigation without waiting for a software release; because PCC Agent applies them on the server, someone who modifies the software on their own device cannot disable them.

When PCC Agent invokes a language model for a supported use case, it applies rejection patterns at two points:

If any pattern matches the part of the request that PCC Agent checks, PCC Agent returns a safety rejection to the client, and the language model is never called.
If inference runs, PCC Agent matches the model response against another set of regular-expression rejection patterns as the response streams. If any pattern matches, PCC Agent stops the stream and returns a safety rejection to the client.

For the response path, the rule set determines whether PCC Agent checks each token before or after emitting it. Checking after emission keeps tokens flowing, but matched content may already reach the device by the time the block fires. Checking before emission helps keep matched content from reaching the device, at the cost of a per-token delay.

PCC Agent does not export which request it rejected or which rule produced the match, and it publishes no counter of how often specific overrides block a request, so to an observer a rejection reveals at most a one-bit signal about whether a block occurred and exposes none of the user’s content.

PCC Agent receives override rules as a JSON asset through Cloud asset distribution, keyed by the inference identifier that the request’s routing parameters carry. As with every cloud asset, the Request execution log records the asset’s content hash and the Appendix: Apple Intelligence Report surfaces it, so security researchers can observe which override asset processed their request. PCC Agent selects the rules from that identifier alone, not from any device or user identity, so it cannot select different overrides for a particular user.

Where no asset supplies rules for a request, PCC Agent applies a small set of built-in patterns that ship with its software, and that request’s log entry contains no override asset hash.

The patterns themselves are not published, because revealing a deny list may limit its effectiveness. We deliberately bounded what an override can do: it can reject a request or a response, but it cannot modify either. A blocked request still appears in the Apple Intelligence Report, so an override cannot discard a request without leaving a user-visible record.

The override code in PCC Agent is part of PCC’s published software.

Content-safety guardrail

PCC Agent can also apply a server-side content-safety guardrail to a model request concurrently with the inference. The guardrail is itself a model: a safety classifier that screens request text, images, or both for unsafe content based on use-case-specific needs. PCC Agent invokes it through the same delegated tool call path it uses for any other model, so the classification runs on its own inference node, separate from the agent node that orchestrates the workflow. Because that node lies inside the PCC trust boundary, screening introduces no new flow of data into or out of PCC.

The guardrail classifies content into multiple safety categories. A per-use-case configuration determines which categories trigger a rejection. If the content triggers a configured category, PCC Agent returns a safety rejection to the client and stops forwarding the model’s output. As with the safety override, PCC Agent does not separately log which request the guardrail rejected, nor the reason the guardrail gave for the rejection, so to an observer a rejection reveals at most a one-bit signal about whether a block occurred and exposes none of the user’s content. The safety classifier is delivered through the same Foundation model and adapter cryptexes as PCC’s other models.

Recitation prevention

To detect and block model output that reproduces content verbatim, PCC Agent generates fingerprints over the output stream using a finite state machine (FSM) and queries Private Filter Service. When fingerprints match the filter, a fuzzy-matching algorithm compares the output against the user’s input; matches present in the input are ignored, so tasks such as proofreading don’t trigger a block. If the length of remaining matched content exceeds a configured threshold, PCC Agent returns an error to the client and blocks further output.

Recitation prevention in PCC Agent, including the FSM code, is part of PCC’s published software, and researchers can inspect it in the Virtual Research Environment. The configuration that drives production of the fingerprints ships separately in a Codeless cryptexes and sits outside PCC’s verifiable transparency guarantees. The recitation mechanism is designed to bound what this configuration can do. The configuration is data, not executable code: it specifies normalization and segmentation rules along with a blocking threshold, and the resulting fingerprints are fixed-width lookups containing no device or user identity. It cannot execute code, change how a request is routed, or send anything outside the trust boundary.