AgentCore IAM Setup for Platform Operators

This guide is for Vell platform operators running the SaaS application using your own AWS account. If you're setting up Vell for customers to use their own AWS accounts (BYOC), see AgentCore BYOC Setup instead.

For Platform Operators Only

This guide assumes you're operating the Vell platform and need Bedrock permissions in your own AWS account (where your app runs). This is NOT for customer accounts.

---

Quick Diagnosis

Is your agent success rate 0.0%?

Go to Dashboard → Agents and check the success rate. If it shows 0.0%, your application cannot invoke Bedrock models.

Common causes: 1. IAM user/role missing Bedrock permissions 2. AWS credentials not configured correctly 3. Bedrock not available in your region 4. Service quotas exceeded

---

Current Setup Detection

Based on your AwsServiceProvider.php, you're using AWS credentials from your .env file:

'credentials' => [
    'key'    => config('filesystems.disks.s3.key'),
    'secret' => config('filesystems.disks.s3.secret'),
],

This means you're using AWS Access Keys (IAM user) for Bedrock access.

Your IAM User: vell-ai-bedrock-20251103 Group: vell-ai-bedrock Current Policy: AmazonBedrockFullAccess

---

Step 1: Verify IAM Permissions

Check Your IAM User

1. Log into AWS Console
2. Go to IAM → Users → vell-ai-bedrock-20251103
3. Click Permissions tab

Verify Bedrock Policy

You should see AmazonBedrockFullAccess attached (either directly or via the vell-ai-bedrock group).

If you see it: ✅ Permissions are correct - proceed to Step 2

If you don't see it:

Option A: Via Group (Recommended)

# Add policy to group
aws iam attach-group-policy \
  --group-name vell-ai-bedrock \
  --policy-arn arn:aws:iam::aws:policy/AmazonBedrockFullAccess

Option B: Direct to User

# Add policy directly to user
aws iam attach-user-policy \
  --user-name vell-ai-bedrock-20251103 \
  --policy-arn arn:aws:iam::aws:policy/AmazonBedrockFullAccess

Understanding AmazonBedrockFullAccess

This AWS managed policy grants: - ✅ bedrock:InvokeModel - Invoke foundation models - ✅ bedrock:InvokeModelWithResponseStream - Stream responses - ✅ bedrock:ListFoundationModels - List available models - ✅ bedrock:GetFoundationModel - Get model details - ✅ bedrock:* - Full Bedrock access (includes custom models, agents, etc.)

Use Least Privilege

AmazonBedrockFullAccess is convenient but overly permissive. For production, use a custom policy with only model invocation permissions (see below).

---

Step 2: Verify AWS Credentials Configuration

Check .env File

Your Bedrock service uses S3 credentials. Verify these are set:

# .env file
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=us-east-1

Test Credentials

# Test if credentials work
aws sts get-caller-identity \
  --profile default

# Expected output:
# {
#   "UserId": "AIDA...",
#   "Account": "253265132499",
#   "Arn": "arn:aws:iam::253265132499:user/vell-ai-bedrock-20251103"
# }

Test Bedrock Access

# List available Bedrock models
aws bedrock list-foundation-models \
  --region us-east-1

# Expected: List of Claude, Nova, and Stable Diffusion models

If this fails: Your credentials don't have Bedrock permissions - go back to Step 1.

If this succeeds: Your IAM permissions are correct! ✅

---

Step 3: Verify Regional Availability

Not all Bedrock models are available in all regions.

Check Your Region

In AwsServiceProvider.php:

'region' => config('filesystems.disks.s3.region'),

Check your .env:

AWS_DEFAULT_REGION=us-east-1  # or us-west-2, eu-west-1, etc.

Model Availability by Region

Region	Claude 3.5	Amazon Nova	Stable Diffusion
us-east-1	✅	✅	✅
us-west-2	✅	✅	✅
eu-west-1	✅	❌	✅
eu-central-1	✅	❌	✅
ap-southeast-1	✅	❌	✅
ap-northeast-1	✅	❌	✅

Nova Model Availability

Amazon Nova models are currently only available in us-east-1 and us-west-2. If your region is different, Nova invocations will fail.

Recommended: Use us-east-1 for broadest model support.

Change Region (if needed)

Update .env:

AWS_DEFAULT_REGION=us-east-1

Restart your application:

php artisan config:clear
php artisan cache:clear

---

Step 4: Test Bedrock Integration

Test via Artisan Command

Create a test command to verify Bedrock works:

php artisan tinker

// Test Bedrock service
$bedrock = app(\App\Services\Bedrock\BedrockRuntimeService::class);

// Test Claude invocation
$response = $bedrock->invokeModel(
    'anthropic.claude-3-5-haiku-20241022-v1:0',
    'Hello, respond with just "OK"'
);

echo $response; // Should output: "OK"

If this works: ✅ Bedrock is fully functional!

If this fails: Check error message and see Troubleshooting section below.

Test via Agent Execution

1. Go to Dashboard → Agents
2. Create a test agent with generate_text capability
3. Run a simple task: "Generate a short greeting"
4. Check execution status

Success: Status shows "Completed" ✅ Failure: Status shows "Failed" - check error message

---

Least Privilege IAM Policy (Recommended)

Instead of AmazonBedrockFullAccess, use this custom policy for production:

Create Custom Policy

1. Go to IAM → Policies → Create policy
2. Use JSON editor:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BedrockModelInvocation",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": [
        "arn:aws:bedrock:*::foundation-model/anthropic.claude-*",
        "arn:aws:bedrock:*::foundation-model/amazon.nova-*",
        "arn:aws:bedrock:*::foundation-model/stability.stable-diffusion-*"
      ]
    },
    {
      "Sid": "BedrockModelDiscovery",
      "Effect": "Allow",
      "Action": [
        "bedrock:ListFoundationModels",
        "bedrock:GetFoundationModel"
      ],
      "Resource": "*"
    }
  ]
}

1. Name it: VellAgentCoreBedrockInvoke
2. Attach to your IAM user or group

Remove Overly Permissive Policy

# Remove full access policy
aws iam detach-group-policy \
  --group-name vell-ai-bedrock \
  --policy-arn arn:aws:iam::aws:policy/AmazonBedrockFullAccess

# Attach least privilege policy
aws iam attach-group-policy \
  --group-name vell-ai-bedrock \
  --policy-arn arn:aws:iam::253265132499:policy/VellAgentCoreBedrockInvoke

---

Alternative: Use IAM Role (ECS/EC2)

If your app runs on ECS or EC2, you can use an IAM role instead of access keys.

For ECS Tasks

1. Create IAM role with Bedrock permissions
2. Attach role to ECS task definition
3. Remove credentials from .env:

   # Remove these lines:
   # AWS_ACCESS_KEY_ID=...
   # AWS_SECRET_ACCESS_KEY=...
   

4. AWS SDK automatically uses task role

For EC2 Instances

1. Create IAM role with Bedrock permissions
2. Attach role to EC2 instance
3. Remove credentials from .env
4. AWS SDK automatically uses instance role

Benefits: - ✅ No long-lived access keys - ✅ Automatic credential rotation - ✅ Better security posture - ✅ Easier audit trail

---

Troubleshooting

Success Rate Still 0.0%

Symptom: After adding permissions, agents still fail

Checks: 1. ✅ Wait 2-3 minutes for IAM propagation 2. ✅ Restart your application: php artisan config:clear 3. ✅ Check application logs: tail -f storage/logs/laravel.log 4. ✅ Verify credentials in .env match IAM user

Debug:

# Check which credentials the app is using
php artisan tinker

config('filesystems.disks.s3.key'); // Should match AWS_ACCESS_KEY_ID
config('filesystems.disks.s3.region'); // Should be us-east-1 or us-west-2

"Access Denied" Errors

Error in logs: User: arn:aws:iam::253265132499:user/vell-ai-bedrock-20251103 is not authorized to perform: bedrock:InvokeModel

Solutions: 1. Verify IAM policy is attached:

aws iam list-attached-user-policies --user-name vell-ai-bedrock-20251103
aws iam list-attached-group-policies --group-name vell-ai-bedrock

2. Check policy document has bedrock:InvokeModel action 3. Verify resource ARN matches the model you're trying to use

"Model Not Found" Errors

Error: Could not resolve the foundation model from the model identifier

Causes: 1. Model not available in your region (see regional table above) 2. Model ID typo (check spelling) 3. Model deprecated or renamed

Test specific model:

# Test Nova Lite in us-east-1
aws bedrock invoke-model \
  --model-id amazon.nova-lite-v1:0 \
  --body '{"prompt":"Hello","max_tokens":10}' \
  --region us-east-1 \
  response.json

Credentials Not Working

Error: The security token included in the request is invalid

Solutions: 1. Regenerate access keys:

aws iam create-access-key --user-name vell-ai-bedrock-20251103

2. Update .env with new keys 3. Restart application

Region Mismatch

Error: Model works in us-east-1 but fails in eu-west-1

Solution: - For Claude 3.5: Available in most regions ✅ - For Amazon Nova: Only us-east-1 and us-west-2 ❌ - Change region in .env to us-east-1

Service Quota Exceeded

Error: Too many requests

Solutions: 1. Check Bedrock service quotas:

aws service-quotas list-service-quotas \
  --service-code bedrock \
  --region us-east-1

2. Request quota increase in AWS Console 3. Implement rate limiting in your app

---

Cost Monitoring

Since you're paying for all customer Bedrock usage, monitor costs:

Enable Cost Allocation Tags

Tag Bedrock invocations by customer/agent:

// In BedrockRuntimeService, add tags to API calls
$this->client->invokeModel([
    'modelId' => $modelId,
    'body' => $body,
    // Note: Bedrock doesn't support request tags yet
    // Track usage in your database instead
]);

Track Usage in Database

Log all invocations to track per-customer costs:

// In AgentExecution model
public function addBedrockUsage(string $modelId, int $inputTokens, int $outputTokens)
{
    $this->increment('tokens_used', $inputTokens + $outputTokens);

    // Calculate cost based on model pricing
    $cost = $this->calculateModelCost($modelId, $inputTokens, $outputTokens);
    $this->increment('bedrock_cost_cents', $cost);
}

Set Up Cost Alerts

In AWS Cost Explorer: 1. Create budget for Bedrock service 2. Set alerts at 50%, 80%, 100% thresholds 3. Get notified before costs spike

---

Production Checklist

Before going to production:

• IAM user has least privilege policy (not AmazonBedrockFullAccess)
• AWS credentials stored securely (AWS Secrets Manager or env)
• Region set to us-east-1 or us-west-2 for Nova support
• CloudTrail enabled for audit logging
• Cost alerts configured
• Rate limiting implemented
• Error handling and retries configured
• Usage tracking in database
• Backup IAM access keys stored securely
• Test all agent capabilities
• Success rate > 95%

---

Alternative Architectures

Multi-Region Setup

To support customers globally, deploy to multiple regions:

// AwsServiceProvider.php
public function register(): void
{
    // Primary region (Nova + Claude)
    $this->app->singleton('bedrock.us-east-1', function () {
        return new BedrockRuntimeService([
            'region' => 'us-east-1',
            'credentials' => [...],
        ]);
    });

    // EU region (Claude only)
    $this->app->singleton('bedrock.eu-west-1', function () {
        return new BedrockRuntimeService([
            'region' => 'eu-west-1',
            'credentials' => [...],
        ]);
    });
}

Route customers to nearest region with model support.

Hybrid: SaaS + BYOC

Offer both models: 1. Default: Use your AWS account (current setup) 2. Enterprise: Let customers use their own AWS account (BYOC guide)

Track which model each customer uses:

// Company model
public function getBedrockService()
{
    if ($this->has_byoc_bedrock) {
        // Use customer's AWS account
        return app(BYOCBedrockService::class)->forCompany($this);
    }

    // Use Vell's AWS account
    return app(BedrockRuntimeService::class);
}

---

Next Steps

Once Bedrock is working:

1. ✅ Test Agents - Run test workflows, verify success rate
2. ✅ Monitor Costs - Set up cost tracking and alerts
3. ✅ Optimize Models - Use Nova Lite for simple tasks, Claude for complex
4. ✅ Set Up BYOC - Offer enterprise customers their own AWS option
5. ✅ Implement Caching - Cache common responses to reduce costs

---

Related Documentation

• BedrockRuntimeService Source (GitHub)
• AgentCore Overview (GitHub)
• BYOC Setup for Customers (if offering enterprise BYOC)
• AWS IAM Best Practices

---

Support

Need help?

• 📧 Email: support@vell.ai
• 💬 Slack: #platform-ops (internal)
• 📚 AWS Bedrock Docs: https://docs.aws.amazon.com/bedrock/

---

Last Updated: November 2025 Audience: Vell Platform Operators Version: 1.0