Table of Contents

Create a Model Agnostic Agent with Claude

This step-by-step guide walks you through creating a model agnostic agent that uses Claude, with the Code tool for running Python and the Knowledge tool for searching files that users upload.

Overview

A model agnostic agent uses the generic agent workflow with the FoundationaLLMFunctionCallingWorkflow class from the foundationallm_agent_plugins package. The workflow lets the main model decide which tools to call, so the same agent design works with Claude, GPT models, and other completion models.

The agent you build here has:

  • Code: writes and runs Python code in an isolated code session.
  • Knowledge: answers questions from files uploaded to the conversation.
  • Tool routing: the main model selects tools based on the user's question.

Prerequisites

  • A Claude completion AI model. For Amazon Bedrock, the model must use a Bedrock API endpoint; for the Anthropic Messages API (Anthropic or Azure AI Foundry), an Anthropic API endpoint. See AI Models.
  • The GenericAgentWorkflow workflow and the foundationallm_agent_plugins Python plugin package installed in your instance.
  • The FoundationaLLM platform prompts and platform tools installed (they provide the Platform-Agent-* prompts and the Code and Knowledge tools in the Tool Library).
  • A code session provider for the Code tool. The tool's default provider is AzureContainerAppsCustomContainer.
  • The Agents Contributor role on the instance.

Part 1: Set Claude Model Parameters

Set Claude-specific parameters on the AI model so the workflow and every tool that uses the model receive the same values.

Important: Claude Sonnet 5 changed an important default: adaptive thinking is on by default, and its default effort is high. Anthropic also states that max_tokens is a hard limit across thinking and visible response text. If thinking output is not configured to be displayed, those tokens may be invisible to your application.

For Claude on a Bedrock endpoint:

  1. In the sidebar, select Agents > Models and open your Claude model.

  2. Under "What are the model parameters?", add a property:

    • Property Key: additional_model_request_fields

    • Property Type: Object / Array

    • Property Value:

      {
  "thinking": {
    "type": "adaptive"
  },
  "output_config": {
    "effort": "high"
  }
}

  3. Add another property: Property Key max_tokens, Property Type Number, Property Value 16000 (or higher at high, xhigh, or max effort).

  4. Make sure temperature, top_p, and top_k are not set. Non-default sampling values return 400 on Claude Sonnet 5.

  5. Select Save Changes.

Rules to keep in mind:

  • effort must sit in output_config, not inside thinking.
  • Do not use "type": "enabled" with budget_tokens; it returns 400 on Sonnet 5.
  • A top-level thinking property is ignored.
  • On Bedrock, use max_tokens; max_new_tokens is not applied.

For Claude on an Anthropic endpoint, max_new_tokens is sent as max_tokens. See Claude and Claude on Amazon Bedrock for the full parameter tables.

Part 2: Create the Agent and Select the Workflow

  1. In the sidebar, select Agents > Agents, then select Create Agent.
  2. Open the Workflow tab.
  3. Under "What workflow should the agent use?", select GenericAgentWorkflow.
  4. Set the workflow fields:
Field Value
Workflow name MAA-Workflow (or keep the default Agent-Workflow)
Workflow package name foundationallm_agent_plugins
Workflow class name FoundationaLLMFunctionCallingWorkflow
Workflow host LangChain

Select the workflow before you set Max rounds on Basic Settings, because selecting a workflow on a new agent resets the workflow properties.

Part 3: Basic Settings

On the Basic Settings tab:

Field Value
Agent Display Name A user-friendly name, for example Claude Analysis Agent
Agent name A unique name, for example claude-maa-agent (wait for ✔️)
Description The purpose of the agent
Main model Your Claude model
Max rounds Optional. For example 5 to allow several tool-calling rounds. Leave 0 for a single round.
Enable tool escalation Optional
What is the main workflow prompt? Your agent's system prompt

Example main workflow prompt:

You are an analysis assistant that answers questions about the user's files and data.
Use the available tools when you need to read uploaded files or run calculations.
Provide concise, accurate answers.

When you select the Claude model, its parameters (including additional_model_request_fields and max_tokens) are copied into Workflow main model parameters on the Workflow tab. Review that list and remove any temperature, top_p, or top_k entries. Parameters there apply to the workflow model only.

Part 4: Add the Workflow Prompts

The FoundationaLLMFunctionCallingWorkflow class requires a router prompt. The files and final prompts are optional but recommended for this agent.

On the Workflow tab, add each resource under Additional workflow resources:

  1. Select the add icon.
  2. Set Resource Type to Prompt.
  3. Type at least three characters to search, then select the prompt.
  4. Enter the Resource Role.
  5. Select Save.
Resource Role Prompt
router_prompt Platform-Agent-Workflow-Router-Multi-Round if Max rounds is above 0, otherwise Platform-Agent-Workflow-Router
files_prompt Platform-Agent-Workflow-Files
final_prompt Platform-Agent-Workflow-Final

The platform router prompts list the agent's tools automatically, so tool names don't need to match the prompt text. To customize the instructions, create your own prompts with the Agent Workflow category under Agents > Prompts and select those instead.

Part 5: Allow File Uploads

On the Portal Experience tab, set Would you like to allow the user to upload files? to Yes.

Part 6: Add the Code Tool

  1. Open the Tools tab and select Add Tool.
  2. In the Tool Library, expand the FoundationaLLM family, select Select next to Code, and select Add to Agent.
  3. In the Edit Agent Tool: Code dialog:
Section Setting Value
Basics Name Code (default)
Resource References Main Model Your Claude model
Resource References Main Prompt Platform-Agent-Tool-Code-Main (default)
Resource References Router Prompt Platform-Agent-Tool-Code-Router (default)
Settings Code Session Required true (default)
Settings Code Session Language Python (default)
Settings Code Session Provider AzureContainerAppsCustomContainer (default)
  1. Do not change the Temperature field under Main Model for Claude Sonnet 5. It shows 0.2, but a value is stored only when you change it.
  2. Select Save changes.

Part 7: Add the Knowledge Tool

  1. Select Add Tool again.
  2. In the FoundationaLLM family, select Select next to Knowledge, and select Add to Agent.
  3. In the Edit Agent Tool: Knowledge dialog:
Section Setting Value
Basics Name Knowledge (default)
Resource References Main Model Your Claude model
Resource References Main Prompt Platform-Agent-Tool-Knowledge-Main (default)
Resource References Router Prompt Platform-Agent-Tool-Knowledge-Router (default)
Resource References Rewrite Prompt Platform-Agent-Tool-Knowledge-Rewrite (default, optional)
Resource References File Upload Data Pipeline DefaultFileUpload (default)
Resource References Conversation Knowledge Unit Conversations (default)
Resource References Agent Private Store Knowledge Unit AgentPrivateStores (default)
Resource References Knowledge Source Agents (default)
  1. Keep the default Settings (for example Vector Store Provider = conversation). As with the Code tool, leave Temperature unchanged for Claude Sonnet 5.
  2. Select Save changes.

The Tools available to the agent table now lists Code and Knowledge. For more on the tool editor, see Tools.

Part 8: Create the Agent

  1. Select Create Agent at the top right.
  2. If a required field is missing, the editor switches to the tab with the problem.
  3. When the message "Agent "[name]" was successfully created!" appears, the portal returns to the Agents page.

Testing Your Agent

  1. Open the User Portal and select your new agent.
  2. Test file upload and knowledge search:
    1. Upload a document (PDF, Word, and so on).
    2. Ask questions about its content.
  3. Test the Code tool:
    1. Ask for a calculation or data analysis.
    2. Ask for a chart or a generated file.

Troubleshooting

"No router prompt found in workflow configuration"

Add a workflow resource with the router_prompt role (Part 4).

Tools are never selected

  • Confirm both tools appear in Tools available to the agent.
  • Confirm the router prompt is attached with the role router_prompt.
  • If Max rounds is above 0, use Platform-Agent-Workflow-Router-Multi-Round.

File upload is not available in the User Portal

  • Set Would you like to allow the user to upload files? to Yes on the Portal Experience tab.
  • Confirm the Knowledge tool's File Upload Data Pipeline reference points to an existing pipeline (DefaultFileUpload by default).

Code execution fails

  • Check the code session provider configuration for your instance.
  • Confirm Code Session Provider in the Code tool's Settings matches an available provider.

Completions return 400

  • Remove temperature, top_p, and top_k from the AI model and from Workflow main model parameters.
  • Use adaptive thinking ("type": "adaptive") with output_config.effort; do not send budget_tokens.
  • Confirm the model uses the intended endpoint provider (Bedrock or Anthropic). See AI Models.

Replies are truncated or look empty

  • Thinking tokens count toward max_tokens even when the thinking text is not returned.
  • Raise max_tokens or lower effort.