How to Configure Multi-Profile AWS Credentials for Bedrock Models in Neuro-San

To configure multi-profile AWS credentials for Bedrock models in Neuro-San, set the credentials_profile_name field in your agent-network HOCON file's llm_config block to specify which AWS profile to use.

The cognizant-ai-lab/neuro-san-studio repository provides a framework for building agent networks that can leverage Amazon Bedrock models. When deploying across multiple AWS environments—such as separate development, staging, and production accounts—you need explicit control over which credential profile each agent network uses to access Bedrock services.

Understanding AWS Credential Resolution in Neuro-San

Neuro-San implements the standard boto3 credential-resolution flow when initializing Bedrock connections. The system evaluates credentials in a specific hierarchy, allowing flexibility for both single-profile and multi-profile deployments.

The Resolution Order

According to the source code in docs/user_guide.md, Neuro-San resolves AWS credentials through the following priority:

1. Environment variables – AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION (or AWS_DEFAULT_REGION) are checked first. This approach works for simple, single-profile setups.

2. Named profile – When the credentials_profile_name field is present in the HOCON llm_config, Neuro-San loads that specific profile from ~/.aws/credentials or ~/.aws/config, regardless of any AWS environment variables that may be set.

3. Fallback – If no profile is specified, the system uses the default profile, or on EC2 instances, automatically retrieves credentials from the Instance Metadata Service.

The full resolution order follows the standard boto3 credential provider chain documented at boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html.

Configuring Multiple AWS Profiles for Bedrock

To work with distinct AWS accounts or regions across different agent networks, you must explicitly declare the profile name in each network's configuration.

Step 1 – Create AWS Profiles

First, establish your AWS profiles outside the repository using the AWS CLI or by manually editing the credential files:

aws configure --profile dev
aws configure --profile staging
aws configure --profile prod

Each profile stores its own aws_access_key_id, aws_secret_access_key, and optionally a region value in ~/.aws/credentials and ~/.aws/config.

Step 2 – Configure the HOCON File

In your agent-network configuration file (located under registries/**/*.hocon), add the credentials_profile_name field within the llm_config section. If the selected profile does not define a region, you must also specify region_name:

"llm_config": {
    "model_name": "bedrock-us-claude-3-7-sonnet",
    "credentials_profile_name": "prod",
    "region_name": "us-west-2"
}

This configuration directs Neuro-San to authenticate using the prod profile credentials and connect to the Bedrock endpoint in us-west-2. You can find this HOCON structure documented in docs/user_guide.md under the Bedrock section.

Step 3 – Verify the Configuration

Start the Neuro-San server and monitor the startup logs. The logs display the resolved AWS credentials and region for each agent network utilizing Bedrock models, confirming that the correct profile is active.

Complete Configuration Example

Below is a full agent-network HOCON snippet demonstrating multi-profile setup for a development environment:

{
    "agent_name": "my_bedrock_agent",
    "llm_config": {
        "model_name": "bedrock-us-claude-3-7-sonnet",
        "credentials_profile_name": "dev",
        "region_name": "us-east-1"
    },
    "tools": {
        "description": "Tool definitions here"
    },
    "instructions": {
        "description": "Agent instructions here"
    }
}

Place this configuration in the appropriate <network>.hocon file under registries/ and restart Neuro-San. The server will now authenticate to Amazon Bedrock using the dev profile credentials, isolating this agent network from production resources.

Summary

• Explicit profile selection via credentials_profile_name in HOCON files prevents accidental cross-account access when running multiple agent networks.
• Credential resolution follows the standard boto3 chain, but named profiles in the configuration take precedence over environment variables.
• Region configuration can be handled either within the AWS profile or via the optional region_name field in the HOCON file.
• Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION) remain valid for single-profile deployments as shown in .env.example.

Frequently Asked Questions

How do I switch between AWS profiles without restarting Neuro-San?

You cannot hot-swap AWS profiles without restarting. Neuro-San reads the credentials_profile_name from the HOCON files at startup. To switch profiles, modify the credentials_profile_name value in your registries/**/*.hocon file and restart the server. For dynamic multi-account setups, consider running separate Neuro-San instances with different configuration directories.

What happens if I set both environment variables and credentials_profile_name?

When credentials_profile_name is specified in the HOCON configuration, it takes precedence over all environment variables including AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. The system loads credentials exclusively from the named profile in ~/.aws/credentials, ignoring any AWS credentials present in the environment.

Can I use different AWS profiles for different agents within the same network?

Yes. Each agent definition within a network HOCON file contains its own llm_config block. You can assign distinct credentials_profile_name values to individual agents, allowing one agent to use Bedrock in a development account while another uses production credentials, provided both profiles exist in your AWS configuration files.

Do I need to specify region_name if my AWS profile already has a region?

No. If the AWS profile specified in credentials_profile_name includes a region setting in ~/.aws/config, Neuro-San will use that region automatically. Only include the region_name field in the HOCON file when the profile lacks a default region or when you need to override the profile's region for a specific Bedrock endpoint.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}