AWS setup¶

Ark requires an AWS Bedrock Agent and credentials with permission to invoke it.

Bedrock Agent¶

Create an agent¶

Open the AWS Bedrock console
Go to Agents in the left sidebar
Click Create agent
Configure the agent with your desired model, instructions, and optionally a knowledge base
Create an alias for the agent (e.g., "production")

Note the IDs¶

After creation, you need two values:

Value	Where to find it	Env var
Agent ID	Agent details page	`BEDROCK_AGENT_ID`
Agent Alias ID	Agent alias tab	`BEDROCK_AGENT_ALIAS_ID`

AWS credentials¶

Ark supports two authentication methods:

Option 1: AWS profile (recommended for local development)¶

Set AWS_PROFILE to a profile name from ~/.aws/credentials:

# ~/.aws/credentials
[my-profile]
aws_access_key_id = AKIA...
aws_secret_access_key = ...

# ~/.aws/config
[profile my-profile]
region = us-east-1

export AWS_PROFILE=my-profile

When using a profile, the region is automatically read from ~/.aws/config unless AWS_REGION is explicitly set.

Option 2: Explicit keys (recommended for deployment)¶

export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION=us-east-1

For temporary credentials (e.g., from STS AssumeRole), also set:

export AWS_SESSION_TOKEN=...

Priority

Explicit keys always take priority over profile-based credentials.

IAM permissions¶

The IAM user or role needs these permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "bedrock:InvokeAgent",
      "Resource": "arn:aws:bedrock:*:*:agent-alias/*/*"
    }
  ]
}

If using Firehose analytics, also add:

{
  "Effect": "Allow",
  "Action": "firehose:PutRecord",
  "Resource": "arn:aws:firehose:*:*:deliverystream/*"
}

Firehose analytics (optional)¶

Ark can publish every interaction (user message + agent response) to a Kinesis Firehose delivery stream as newline-delimited JSON, for downstream analysis with Athena, Glue, or S3.

To enable:

Create a Firehose delivery stream (e.g., with S3 destination)
Set FIREHOSE_STREAM_NAME to the stream name

If FIREHOSE_STREAM_NAME is not set, analytics are disabled silently.

Event format¶

Each event is a JSON object:

{
  "timestamp": "2026-03-14T10:30:00Z",
  "user_id": "U1234567",
  "thread_id": "1710412200-123456",
  "user_message": "What is our refund policy?",
  "response": "According to our policy document..."
}