Table of Contents

Configure the Claude Agent Tool

This guide explains how to add and configure the Claude Agent tool on an agent in the Management Portal. The Claude Agent tool runs the Anthropic Claude Agent SDK in a sandboxed container so the agent can generate files, execute code, research the web, and automate multi-step tasks.

Overview

The Claude Agent tool is the built-in library tool Platform-Tool-Claude-Agent in the Anthropic tool family. When you add it to an agent, the portal suggests the agent tool name ClaudeAgent.

This tool does not use the workflow language-model path. Adaptive thinking, effort, and Bedrock additional_model_request_fields for a Claude orchestrating model are configured on the AI model. See Claude on Amazon Bedrock.

Prerequisites

  • Access to the Management Portal with permission to edit agents
  • The Claude Agent Session API service deployed and running
  • The Context API configured with Claude Agent code session support
  • An API endpoint whose Provider is Anthropic, configured under Platform > API Endpoints. Its authentication parameters must include an api_key_configuration_name that resolves to a valid Anthropic API key.

Add the Claude Agent Tool to an Agent

  1. In the sidebar, select Agents > Agents, and then select the pencil icon for the agent (or select Create Agent).
  2. Select the Tools tab, and then select Add Tool.
  3. In the Add Tool to Agent dialog, expand the Anthropic folder and select Select on Claude Agent.
  4. Select Add to Agent. The Edit Agent Tool: ClaudeAgent dialog opens.
  5. Review the Name and Description. The description tells the orchestrating model when to call the tool, for example: "Use this tool when the user asks to create files, execute code, generate charts, search the web, or perform multi-step tasks."
  6. Configure the Claude Agent Configuration tabs described below.
  7. Select Save changes, and then save the agent.

To change the defaults used for every new assignment, edit Claude Agent on Agents > Tools instead. Existing agents keep their copy.

Claude Agent Configuration

The Claude Agent Configuration panel has four tabs.

Agent Setup

Setting Description
Anthropic API Endpoint The API endpoint used to call Claude. The list shows only endpoints whose provider is Anthropic.
System Prompt Instructions that define the agent's behavior. Supports markdown. The library default is "Always write files under /claude_data/ unless the user explicitly specifies otherwise. Never write to /tmp."
Skills Skill paths to preload. Type a path and press Enter to add it.

Tools & Security

Permission Mode controls how Claude handles tool permissions:

Mode Description
Bypass Permissions (default) Executes all tools without approval. Best for trusted automated workflows.
Accept Edits Auto-accepts file edits and prompts for other actions
Default Standard permission checking with prompts
Plan Mode Read-only exploration with no file modifications

Server-side execution has no human in the loop, so keep Bypass Permissions unless you have a specific reason to change it.

Allowed Tools lists the Claude Agent SDK tools the agent may use, grouped by category. Use Select All, Select None, or Select Recommended (Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch). The library default is the recommended set plus Skill.

Category Tools
File Operations Read, Write, Edit, Glob, Grep
Web & Search WebSearch, WebFetch
Execution Bash, Skill, Task (Agent), TaskOutput, TaskStop
Planning EnterPlanMode, ExitPlanMode, TodoWrite
Interaction AskUserQuestion
Other NotebookEdit

Disallowed Tools lists tools that are denied even if they are also allowed.

Sandbox settings restrict file system and network access:

Setting Description
Enable Sandbox Runs the agent in an isolated sandbox. Off by default. The remaining settings appear when it is on.
Auto-allow Bash commands when sandboxed Approves Bash commands automatically inside the sandbox
Allow unsandboxed commands Allows commands to run outside the sandbox
Enable weaker nested sandbox Turns on the SDK's weaker nested sandbox option
Excluded Commands Commands that are never allowed
Allow local binding Allows binding to local ports
Allow all Unix sockets Allows all Unix socket connections
HTTP Proxy Port, SOCKS Proxy Port Proxy ports for network access

MCP

MCP servers connect the Claude session to external tools, databases, and APIs. Select Add MCP Server and fill in the MCP Server dialog:

Field Description
Server Name A unique name for the server
Transport Type HTTP, SSE, or Stdio
URL and Headers For HTTP and SSE servers. Use headers for authentication.
Command, Arguments, Environment Variables For Stdio servers, for example command npx with arguments -y, @modelcontextprotocol/server-filesystem, /claude_data
Enabled Whether the server is available to the session

These servers are configured on the tool itself. They are separate from the platform MCP servers on Agents > MCP Servers.

Advanced

Setting Description
Working Directory The directory where the agent reads and writes files. The library default is /claude_data; if you clear the field, /mnt/data is used.
Session Endpoint Overrides Routes specific users to a local development endpoint instead of the deployed service. Select Add URL Exception and enter the User Principal Name (UPN), the Local Endpoint URL, and whether it is Enabled.

Files that Claude creates in the working directory are uploaded to platform storage and returned to users as downloadable content artifacts.

Workflow Configuration

Use a function-calling workflow such as FoundationaLLMFunctionCallingWorkflow (Workflow tab: Workflow package name foundationallm_agent_plugins, Workflow class name FoundationaLLMFunctionCallingWorkflow, Workflow host LangChain).

Important: Instruct the orchestrating model, in the agent's main workflow prompt, to make a single call to the Claude Agent tool with the complete user request. Multiple calls produce duplicate file artifacts.

Portal Experience Settings

On the agent's Portal Experience tab, consider enabling:

Setting Reason
Would you like to allow the user to upload files? Lets users upload files for Claude to process
Would you like to allow the user to see the message prompts? Helps debug tool invocations

Troubleshooting

The Claude Agent Configuration panel does not appear

The panel is shown only for the Claude Agent library tool. Add the tool from the Anthropic folder in Add Tool rather than creating a custom tool with the same class.

"ANTHROPIC_API_KEY is not set" error

  • Select an endpoint in Anthropic API Endpoint.
  • Verify the endpoint's api_key_configuration_name resolves to a valid key in App Configuration.
  • Alternatively, set ANTHROPIC_API_KEY in the Claude Agent Session API environment.

The Anthropic API Endpoint list is empty

Only endpoints with the Anthropic provider are listed. Create or update the endpoint on Platform > API Endpoints.

Duplicate files in responses

Make sure the workflow prompt tells the model to make a single Claude Agent tool call, and avoid prompts that split the request into several calls.

Session errors or timeouts

  • The tool returns errors in the conversation instead of hanging.
  • Check the Claude Agent Session API logs.
  • Verify the Context API can reach the Claude Agent Session API.