AWS DevOps Agent

AWS DevOps Agent is AWS’s incident-investigation agent, hosted in an Agent Space. The integration is two-sided: beeps POSTs the alert to your Agent Space’s webhook URL to start an investigation, then polls task status through the AWS SDK using IAM credentials. The output is an investigation report, not a PR.

Prerequisites

• An AWS account with DevOps Agent enabled and at least one Agent Space configured.
• The Agent Space’s webhook URL.
• The webhook authentication secret. Either an HMAC signing secret (hmac_v1) or a bearer token (bearer_v2), depending on how your Agent Space is configured.
• AWS IAM credentials with the aidevops:* permissions listed in the DevOps Agent IAM docs.
• Optionally: a cross-account roleArn for STS AssumeRole.

Provider-side setup

1. Configure the Agent Space

Follow the AWS DevOps Agent setup guide to create an Agent Space. Note:

• The Agent Space ID (e.g. space-abc123).
• The Agent Space webhook URL (e.g. https://webhook.devopsagent.us-east-1.amazonaws.com/invoke/abc123).
• Whether the webhook uses HMAC v1 or bearer v2 auth.

2. Get the auth secret

• HMAC v1: copy the signing secret from the Agent Space configuration. Beeps will sign each request with HMAC-SHA256.
• Bearer v2: copy the bearer token from the Agent Space configuration. Beeps will send it as Authorization: Bearer <token>.

3. Provision IAM credentials

Create an IAM user (or, preferred for cross-account, a role) with the aidevops:* permissions referenced in the DevOps Agent IAM docs. Beeps uses the access key + secret to call the DevOps Agent SDK (ListBacklogTasksCommand, ListJournalRecordsCommand) when polling.

If you’re going cross-account, create a role in the target account with those permissions and a trust policy allowing the IAM user in your beeps integration account to assume it. Provide the role ARN as roleArn in metadata; beeps will assume it via STS for each poll.

Beeps-side setup

The webhook secret goes in apiKey. Everything else (AWS creds, region, agent space, auth version, optional role) goes in metadata:

const awsDevOpsIntegration = await client.integration.create({
  name: "AWS DevOps Agent - prod",
  provider: "aws_devops",
  apiKey: process.env.AWS_DEVOPS_WEBHOOK_SECRET,
  metadata: {
    awsAccessKeyId: process.env.AWS_ACCESS_KEY_ID,
    awsSecretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    awsRegion: "us-east-1",
    agentSpaceId: "space-abc123",
    authVersion: "hmac_v1", // or "bearer_v2"
    // roleArn: "arn:aws:iam::123456789012:role/beeps-devops-agent",
  },
});

Reference it from a relay rule. Point the rule at the Agent Space webhook URL via endpoint, and pass the Agent Space ID and region so beeps knows where to poll:

await client.relay.rules.create(relayId, {
  name: "AWS DevOps investigation",
  ruleType: "agent",
  config: {
    agentType: "aws_devops",
    integrationId: awsDevOpsIntegration.id,
    endpoint: "https://webhook.devopsagent.us-east-1.amazonaws.com/invoke/abc123",
    awsAgentSpaceId: "space-abc123",
    awsRegion: "us-east-1",
    awsAuthVersion: "hmac_v1",
    awsPriority: "HIGH",
    pollInterval: 60000,
    maxPollAttempts: 60,
  },
});

Configuration reference

Integration metadata

Field	Type	Required	Default	Description
awsAccessKeyId	string	yes	—	IAM access key id
awsSecretAccessKey	string	yes	—	IAM secret access key
awsRegion	string	yes	—	AWS region of the Agent Space, e.g. us-east-1
agentSpaceId	string	yes	—	Agent Space identifier
authVersion	"hmac_v1" | "bearer_v2"	yes	—	Webhook signature scheme
roleArn	string	no	—	IAM role to assume via STS for polling (cross-account)

The apiKey field on the integration holds the webhook secret (the HMAC signing secret or bearer token, depending on authVersion).

Rule config

Field	Type	Required	Default	Description
agentType	"aws_devops"	yes	—	Selects the AWS DevOps agent
integrationId	string	yes	—	The integration’s id
endpoint	string (URL)	yes	—	Agent Space webhook URL
awsAgentSpaceId	string	yes	—	Repeated here so polling can locate it without re-reading the integration
awsRegion	string	yes	—	Repeated here for the same reason
awsAuthVersion	"hmac_v1" | "bearer_v2"	yes	—	Must match the integration’s authVersion
awsPriority	"CRITICAL" | "HIGH" | "MEDIUM" | "LOW"	no	—	Priority sent on the webhook payload
awsService	string	no	—	Service tag added to the investigation

The shared polling and storm-control fields are documented in Relay Rules.

Troubleshooting

Webhook returns 401/403. Check that authVersion on both the integration metadata and the rule config matches what the Agent Space expects. HMAC and bearer use different request signing; they’re not interchangeable.

Polling fails with AccessDenied. The IAM credentials need aidevops:* (see the IAM permissions doc above). For cross-account, also confirm the trust policy on the assumed role allows your IAM user.

roleArn set but polling still uses the base credentials. Beeps assumes the role via STS only if roleArn is present in metadata. Confirm the field is set on the integration (not the rule).