# Pro-code agent templates

When you create a pro-code agent, your code repository is generated from an agent template. The template ships with simplified configuration for [Ontology MCP (OMCP)](../../ontology-mcp/overview/index.md), [Palantir MCP](../../palantir-mcp/overview/index.md), and the [Ontology SDK (OSDK)](../../ontology-sdk/overview/index.md), with common setup provided by the agent library. The template keeps your repository focused on agent logic rather than platform plumbing.

## Supported templates

Templates are available for the following agent frameworks:

* **Claude Agent SDK:** A TypeScript template built on the [Claude Agent SDK ↗](https://platform.claude.com/docs/en/agent-sdk/typescript), for agents that use Claude models. The agent loop is driven by the `query` function, and tools are exposed through MCP servers.
* **OpenAI Agents SDK:** A TypeScript template built on the [OpenAI Agents SDK ↗](https://openai.github.io/openai-agents-js/), for agents that use OpenAI models. The agent loop is driven by the `Agent` and `run` primitives.
* **Google ADK:** A TypeScript template built on the [Google Agent Development Kit (ADK) ↗](https://google.github.io/adk-docs/), for agents that use Google Gemini models. The agent loop is driven by the `Agent` and `InMemoryRunner` primitives. Gemini is routed through the Foundry language model proxy, so no Google API key is required.

These templates share the same [project structure](#project-structure), argument schema, default MCP configurations, and publishing flow. They differ in how the agent loop and custom tools are defined. Select a template when you create your pro-code agent. Unless noted otherwise, the examples in this section use the Claude Agent SDK template.

## Project structure

An agent template code repository has the following structure:

```text
agent/                # Your agent code
├── index.ts          # Agent entry point and argument schema
├── systemPrompt.ts   # System prompt
└── customTools.ts    # Custom tools
utils/                # Shared platform tooling
scripts/              # Build scripts
```

| Path | Description |
| --- | --- |
| `agent/index.ts` | The agent entry point. Defines the `AgentArguments` schema and the `runAgent` function that drives the agent loop. |
| `agent/systemPrompt.ts` | The system prompt that defines how the model behaves. |
| `agent/customTools.ts` | Custom tools the agent can call, exposed through an in-process MCP server. |
| `utils/` | Shared platform tooling used by the template, including OSDK client helpers and publishing commands. |
| `scripts/` | Build scripts used to package the agent for publishing. |

Default MCP configurations for [Palantir MCP](../../palantir-mcp/overview/index.md), [Ontology MCP](../../ontology-mcp/overview/index.md), and [Python Transforms MCP](../../palantir-mcp/overview/index.md#build-and-iterate-on-python-transforms) are provided by the agent library. You retrieve them with the [MCP configuration functions](#mcp-configuration-functions) described below.

:::callout{theme="success"}
To add your own MCP configurations, create a new file under `agent/`, such as `agent/mcps/custom.ts`, and register it in your agent loop the same way as the [MCP configuration functions](#mcp-configuration-functions). Keeping custom configurations in your own files avoids conflicts during repository upgrades.
:::

Palantir MCP provides tools to interact with the platform. [Tool search](../../palantir-mcp/tool-search/index.md) is enabled by default, so your agent discovers tools on demand to reduce token usage. To load the full permitted catalog at startup instead, [disable tool search in your agent configuration](../../palantir-mcp/tool-search/index.md#agents).

## Customize your pro-code agent

### System prompt

Edit `agent/systemPrompt.ts` to change the instructions that define how the pro-code agent behaves.

### Agent arguments

Pro-code agents can accept arguments that are provided for each run. Define them in the `AgentArguments` schema in `agent/index.ts` using `defineInputs`:

```typescript
import { defineInputs, t } from "@palantir/agent-templates-bundle";

export const AgentArguments = defineInputs({
  additionalAgentContext: t.string().optional(),
  // Add your own arguments here
});
```

Arguments are automatically accepted when the agent is invoked and registered as input types when the agent is published to Foundry.

### Custom tools

Edit `agent/customTools.ts` to define tools the agent can call.

For the Claude Agent SDK template, define tools with `tool` and expose them through an in-process MCP server created with `createSdkMcpServer`:

```typescript
import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

tool(
  "my_tool",
  "Description of what this tool does",
  z.object({ param: z.string() }),
  async (params) => {
    return mcpSuccessResponse("result");
  },
);
```

For the OpenAI Agents SDK template, define tools with `tool` from `@openai/agents`:

```typescript
import { tool } from "@openai/agents";

const myTool = tool({
  name: "my_tool",
  description: "Description of what this tool does",
  parameters: {
    type: "object",
    properties: { param: { type: "string" } },
    required: ["param"],
  },
  strict: false,
  execute: async (input) => {
    return "result";
  },
});
```

For the Google ADK template, define tools with `FunctionTool` from `@google/adk`:

```typescript
import { FunctionTool } from "@google/adk";
import { z } from "zod";

const myTool = new FunctionTool({
  name: "my_tool",
  description: "Description of what this tool does",
  parameters: z.object({ param: z.string() }),
  execute: async (input) => {
    return "result";
  },
});
```

### Agent loop

Modify the `runAgent` function in `agent/index.ts` to change the prompt, model, MCP servers, or tools passed to the agent.

For the Claude Agent SDK template, retrieve the Ontology MCP configuration, pass it to the `query` function as an MCP server, and consume the agent's response stream:

```typescript
import { query } from "@anthropic-ai/claude-agent-sdk";
import { getOntologyMcpConfiguration } from "@palantir/agent-templates-bundle/mcp/anthropic";

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 the OpenAI Agents SDK template, construct an `Agent`, connect its MCP servers, run the agent, and consume the result stream:

```typescript
import { Agent, run, MCPServer } from "@openai/agents";

export async function runAgent(args: AgentArgs) {
  const mcpServers: MCPServer[] = [
    // Add MCP servers here
  ];

  for (const server of mcpServers) {
    await server.connect();
  }

  try {
    const agent = new Agent({
      name: "MyAgent",
      instructions: "...",
      mcpServers,
      tools: [myTool],
      model: "gpt-5.4",
    });

    const result = await run(agent, "...", { stream: true });

    // Consume the agent's response stream

    await result.completed;
  } finally {
    for (const server of mcpServers) {
      await server.close();
    }
  }
}
```

For the Google ADK template, construct an `Agent`, run it with an `InMemoryRunner`, and consume the event stream. The template provides a `FoundryGemini` model wrapper, defined in a template-managed `foundryGemini.ts` file, that routes Gemini through the Foundry language model proxy, so no Google API key is required:

```typescript
import { Agent, InMemoryRunner, MCPToolset, stringifyContent } from "@google/adk";
import { FoundryGemini } from "./foundryGemini";

export async function runAgent(args: AgentArgs) {
  const mcpToolsets: MCPToolset[] = [
    // Add MCP toolsets here
  ];

  try {
    const agent = new Agent({
      name: "MyAgent",
      instruction: "...",
      tools: [...mcpToolsets],
      model: new FoundryGemini({ model: "gemini-2.5-flash" }),
    });

    const runner = new InMemoryRunner({ agent });

    for await (const event of runner.runEphemeral({
      userId: "user",
      newMessage: { role: "user", parts: [{ text: "..." }] },
    })) {
      if (event.content) {
        console.log(stringifyContent(event));
      }
    }
  } finally {
    for (const toolset of mcpToolsets) {
      await toolset.close();
    }
  }
}
```

## Add OSDK and OMCP to your pro-code agent

The template makes both OSDK and Ontology MCP available to your pro-code agent without client credentials, through the agent's [scoped permissions](../scoped-permissions/index.md).

### Ontology SDK

To give your pro-code agent access to Ontology resources, add an Ontology SDK to the agent. As when creating an SDK in Code Workspaces, select the object types, action types, and query functions to include, then generate the SDK. For step-by-step guidance, review [Create a new Ontology SDK](../../code-workspaces/ontology/index.md#create-a-new-ontology-sdk).

To read and write Ontology data directly, construct an OSDK client bound to your selected Ontology. The Ontology resource identifier (RID) is exposed by the generated SDK:

```typescript
import { getOntologySdkClient } from "@palantir/agent-templates-bundle";
import { $ontologyRid } from "@ontology/sdk";

const client = await getOntologySdkClient($ontologyRid);
```

For guidance on using the OSDK in your pro-code agent, review the [Ontology SDK documentation](../../ontology-sdk/overview/index.md) and the [TypeScript OSDK reference](../../ontology-sdk/typescript-osdk/index.md).

### Ontology MCP

When you add an Ontology SDK to your pro-code agent, an Ontology MCP is created based on the same SDK resources. The Ontology MCP exposes the object types, action types, and query functions in the SDK as MCP tools that the agent's model can call.

To use Ontology MCP, retrieve its configuration with the `getOntologyMcpConfiguration` function and pass it to your pro-code agent's MCP servers, as described in [MCP configuration functions](#mcp-configuration-functions) below. For more information on the tools Ontology MCP exposes, review the [Ontology MCP documentation](../../ontology-mcp/overview/index.md).

## MCP configuration functions

The agent library provides the default MCP server configurations through the following functions:

| Function | Connects to | Description |
| --- | --- | --- |
| `getOntologyMcpConfiguration` | [Ontology MCP](../../ontology-mcp/overview/index.md) | Exposes the object types, action types, and query functions from your Ontology SDK as tools the model can call. An SDK must be added first, as described in [Ontology SDK](#ontology-sdk). |
| `getPalantirMcpConfiguration` | [Palantir MCP](../../palantir-mcp/overview/index.md) | Provides a wide range of tools to interact with the Palantir platform. |
| `getPythonTransformsMcpConfiguration` | [Python Transforms MCP](../../palantir-mcp/overview/index.md#build-and-iterate-on-python-transforms) | Provides tools to interact with Foundry Python transforms, such as previewing and discovering transforms. |

Each function is `async` and resolves the connection details at runtime. Because the URL, command, and authorization details are resolved through [scoped permissions](../scoped-permissions/index.md), no client ID, secret, or Foundry token is required.

The functions are framework-specific: each returns the MCP server type expected by your agent framework. Import them from the package path that matches your template:

| Framework | Import path | Return type |
| --- | --- | --- |
| Claude Agent SDK | `@palantir/agent-templates-bundle/mcp/anthropic` | `McpHttpServerConfig` or `McpStdioServerConfig` |
| OpenAI Agents SDK | `@palantir/agent-templates-bundle/mcp/openai` | `MCPServerStreamableHttp` or `MCPServerStdio` |
| Google ADK | `@palantir/agent-templates-bundle/mcp/google` | `MCPToolset` |

Remember that each function is asynchronous: await it before registering the result in your agent loop.

For the Claude Agent SDK template, register the resolved configurations in the `mcpServers` map passed to `query`:

```typescript
import { getOntologyMcpConfiguration, getPalantirMcpConfiguration } from "@palantir/agent-templates-bundle/mcp/anthropic";

const [omcpConfig, palantirConfig] = await Promise.all([
  getOntologyMcpConfiguration(),
  getPalantirMcpConfiguration(),
]);

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

For the OpenAI Agents SDK template, collect the resolved servers into the `mcpServers` array passed to `new Agent`:

```typescript
import { getOntologyMcpConfiguration, getPalantirMcpConfiguration } from "@palantir/agent-templates-bundle/mcp/openai";
import { MCPServer } from "@openai/agents";

const [ontologyMcp, palantirMcp] = await Promise.all([
  getOntologyMcpConfiguration(),
  getPalantirMcpConfiguration(),
]);
const mcpServers: MCPServer[] = [ontologyMcp, palantirMcp];
```

For the Google ADK template, add each resolved `MCPToolset` to the agent's `tools` array:

```typescript
import { getOntologyMcpConfiguration, getPalantirMcpConfiguration } from "@palantir/agent-templates-bundle/mcp/google";
import { MCPToolset } from "@google/adk";

const [ontologyMcp, palantirMcp] = await Promise.all([
  getOntologyMcpConfiguration(),
  getPalantirMcpConfiguration(),
]);
const mcpToolsets: MCPToolset[] = [ontologyMcp, palantirMcp];
```

Palantir MCP and Python Transforms MCP require your Foundry front-door host (`FOUNDRY_EXTERNAL_HOST`). This host is resolved for you at runtime from Control Panel using the agent's own credentials. It therefore remains correct even when the agent is installed on a different enrollment through Marketplace. If the host cannot be resolved, the configuration falls back to the host recorded when the repository was generated. To override the fallback, pass a `fallbackHost` option to `getPalantirMcpConfiguration` or `getPythonTransformsMcpConfiguration`.

## Next steps

* [Publish and call a pro-code agent.](../publish-and-call/index.md)
* [Learn how the agent authenticates without client credentials.](../scoped-permissions/index.md)