Build an agent in Foundry

This guide walks you through building a pro-code agent, from creating a repository to publishing an agent that you can call from Workshop or the Ontology SDK.

Prerequisites

Before you begin, ensure that you have the following:

• Access to an Ontology that your agent will read from and write to.
• Permissions to create a code repository in your Foundry environment.

Step 1: Create the agent

First, create a new agent to generate a code repository from an agent template. From the repository configuration page, complete the following:

1. Enter a Name for your agent and select a Location for the repository.
2. Set the Repository type to your agent framework. Repository types are available for the Claude Agent SDK ↗, OpenAI Agents SDK ↗, and Google Agent Development Kit (ADK) ↗.
3. Select the Ontology your agent will use. This selector is required, and it determines the Ontology binding used by the agent's scoped permissions.
4. Review the Agent API name. The name is auto-generated from the repository name and can be edited. The agent API name identifies your agent's function when it is called from Workshop or OSDK.

Once the repository is generated, you are navigated to the Build agents in Foundry page and guided through the next steps of building your agent.

The generated repository follows the structure described in the documentation, with your agent logic in the agent/ directory and shared platform tooling in utils/.

Step 2: Configure the agent

The generated repository ships with simplified configuration for the Ontology SDK (OSDK), Ontology MCP (OMCP), and Palantir MCP. Because the agent uses scoped permissions, you do not need to provide a client ID, secret, or Foundry token.

Construct the OSDK client bound to your Ontology and retrieve the Ontology MCP configuration:

Copied!
1
2
3
4
5
import { getOntologySdkClient } from "@palantir/agent-templates-bundle";
import { getOntologyMcpConfiguration } from "./mcps/default";
import { $ontologyRid } from "@ontology/sdk";

const client = await getOntologySdkClient($ontologyRid);

Step 3: Define the agent's logic

Implement the agent's behavior in the runAgent entry point. Define the prompt, pass the OMCP configuration to the model query as an MCP server, and consume the agent's response stream:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
export async function runAgent(args: AgentArgs) {
  const omcpConfig = await getOntologyMcpConfiguration();

  const iter = query({
    prompt: "...",
    options: {
      mcpServers: {
        ["ontology_mcp"]: omcpConfig,
      },
    },
  });

  // Consume the agent's response stream
}

For more detail on the configuration the template provides, review Agent templates.

Step 4: Test the agent locally

During development, run the agent locally to test its behavior. Open a terminal in your repository, install dependencies, and start the agent, providing any arguments defined in your AgentArguments schema:

Copied!
1
2
npm install
npm start -- --json-args '{"additionalAgentContext": "some context"}'

You can also provide arguments from a JSON file with --json-args-file.

Before you publish, build the agent and confirm that it completes with no errors:

Copied!
1
npm run build

Step 5: Publish the agent

When your agent builds successfully, publish it by tagging a version. Tagging registers the agent with its Ontology binding and agent API name, and the template's continuous integration deploys the tagged build as an asynchronous Foundry function.

First, commit your changes. You can edit and commit from the in-platform code repository interface or from your editor with the Palantir extension for Visual Studio Code.

Then tag a version in either of the following ways:

• Repository interface: Select Tag version to tag a release off your default branch, set the tag name based on the extent of your changes, and then select Tag and release. This flow mirrors how other TypeScript functions are published.
• Git tag: Create and push a git tag from your local clone, for example git tag 1.0.0 followed by git push --tags.

Step 6: Run the agent

After publishing, we recommend running the agent from Automate using a function effect that points at the agent's function. You can also call the agent from Workshop, the Ontology SDK, and Ontology actions.

Because an agent function returns no value, have your agent write its results to Ontology objects to consume its output. For details and caveats, review Publish and call an agent.

Next steps

• Manage the SDK and OMCP scope from your editor with Continue.
• Learn how the agent authenticates without client credentials.