Develop pro-code agents on a global branch

Pro-code agents integrate with Global Branching, allowing you to develop and test agent code alongside branched Ontology and application changes without affecting the main branch. An agent running on a global branch uses that branch automatically for Ontology SDK (OSDK) and Ontology MCP reads and writes.

Prerequisites

Before developing a pro-code agent on a global branch, ensure that:

• Global Branching and branching for agents are enabled on your enrollment. Contact Palantir Support to request access.
• You have a role that allows you to edit the agent's code repository, such as the default Editor or Owner role on its Project.
• The agent repository uses a template version that supports Global Branching. If Foundry reports that the repository is outdated when you add it to a branch, upgrade the repository and try again.

Add an agent repository to a global branch

To develop an agent on a global branch:

1. Open the agent's code repository or code workspace.
2. Open the branch selector, then create or select a global branch.
3. If prompted, select Add to add the repository to the branch.

Foundry creates a repository branch associated with the global branch and checks it out in the code workspace. Commit agent code changes to this repository branch as you iterate.

Test an agent on a global branch

Run the agent from the code workspace with npm run start, as described in Build a pro-code agent in Foundry. The agent template resolves the global branch associated with the checked-out repository branch. OSDK and Ontology MCP operations then read from and write to that global branch.

If your agent calls an action, index the action's target object type on the same global branch before testing the action. In Ontology Manager, select the global branch, open the target object type, then select Index object type from the banner. Wait for indexing to finish before running the agent.

Published agent functions also receive the global branch context when invoked from a resource on the same global branch. A branched agent function and the data it writes are isolated from main and from other global branches.

Publish an agent on a global branch

Publishing makes the agent function available to resources on the same global branch:

1. Commit the agent changes you want to publish.
2. Select Tag version in the repository interface.
3. Select the global branch and choose a stable version target. The version target is the version that will be published to main when the global branch is merged.
4. Select Tag and release.

Foundry creates a branched pre-release version and publishes the agent function to the global branch. Do not create the tag with Git directly; the repository interface creates the version required for a global branch.

You can republish to the same version target while iterating. Resources on the global branch that use the version target automatically resolve the latest branched pre-release. The published function is not available from main or from another global branch.

Merge an agent from a global branch

When the agent and its dependent resources are ready, create and merge a global branch proposal. Foundry merges the repository changes and publishes the selected stable version target to main. Resources that used the branched version target then resolve the stable version on main.

Before merging, ensure that the version target is still available on main and resolve any checks shown in the Global Branching application.

Next steps

• Publish and call a pro-code agent
• Learn more about the Global Branching workflow