import * as bedrock from "@distilled.cloud/aws/bedrock-agent";
import * as iam from "@distilled.cloud/aws/iam";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
import { toWireDays, toWireSeconds } from "alchemy/Util/Duration";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import { bedrockModelArns } from "./ModelArns.ts";
/**
* A guardrail attached to an agent to apply content filters, denied topics,
* word filters, and sensitive-information policies to model interactions.
*/
export interface AgentGuardrailConfiguration {
/** The unique identifier of the guardrail. */
guardrailIdentifier?: string;
/** The version of the guardrail. */
guardrailVersion?: string;
}
/**
* Long-term memory configuration for an agent — lets the agent retain
* conversational context across sessions as asynchronously generated
* session summaries, readable at runtime via the `GetAgentMemory` binding.
*/
export interface AgentMemoryConfiguration {
/**
* The types of memory to enable. `"SESSION_SUMMARY"` is currently the
* only supported type.
*/
enabledMemoryTypes: bedrock.MemoryType[];
/**
* How long the agent retains memory (e.g. `"30 days"` or
* `Duration.days(30)`; a bare number is milliseconds). Between 1 and
* 365 days. Sent to the API as whole days (`storageDays`).
* @default 30 days
*/
storage?: Duration.Input;
/**
* Configuration for `SESSION_SUMMARY` memory.
*/
sessionSummaryConfiguration?: {
/** The maximum number of recent session summaries to include. */
maxRecentSessions?: number;
};
}
export interface AgentProps {
/**
* Name of the agent (1-100 characters; letters, digits, and the
* characters `_-`). If omitted, a deterministic physical name is
* generated from the app, stage, and logical ID. Changing the name
* triggers a replacement.
*/
agentName?: string;
/**
* The foundation model or inference-profile id the agent uses for
* orchestration — a foundation-model id
* (`anthropic.claude-3-5-sonnet-20240620-v1:0`), a cross-region inference
* profile id (`us.anthropic.claude-3-5-sonnet-20240620-v1:0`), or a full
* Bedrock ARN. Model access must be enabled in the account.
*/
foundationModel: string;
/**
* Instructions that tell the agent what it should do and how it should
* interact with users. Must be at least 40 characters for the agent to be
* preparable.
*/
instruction: string;
/**
* A description of the agent.
*/
description?: string;
/**
* The ARN of an existing IAM role for the agent to assume. When omitted,
* an execution role is created automatically with `bedrock.amazonaws.com`
* trust and `bedrock:InvokeModel` granted on {@link AgentProps.foundationModel}.
*/
agentResourceRoleArn?: string;
/**
* How long the agent retains an idle session before it is ended (e.g.
* `"30 minutes"` or `Duration.minutes(30)`; a bare number is milliseconds).
* Between 1 minute and 1 hour. Sent to the API as whole seconds
* (`idleSessionTTLInSeconds`).
* @default 600 seconds
*/
idleSessionTTL?: Duration.Input;
/**
* The ARN of a KMS key to encrypt the agent with.
*/
customerEncryptionKeyArn?: string;
/**
* A guardrail to apply to the agent's model interactions.
*/
guardrailConfiguration?: AgentGuardrailConfiguration;
/**
* Long-term memory configuration. When enabled the agent summarizes each
* session after it ends and retains the summaries for
* {@link AgentMemoryConfiguration.storage}, making them available to
* later sessions that share the same memory id (and to the
* `GetAgentMemory` / `DeleteAgentMemory` runtime bindings).
*/
memoryConfiguration?: AgentMemoryConfiguration;
/**
* Whether to prepare the agent (compile the DRAFT version) after every
* create and update so it is invocable and can back an
* {@link AgentAlias}. Preparation is polled to completion.
* @default true
*/
prepare?: boolean;
/**
* Tags to apply to the agent. Merged with internal Alchemy tags.
*/
tags?: Record<string, string>;
}
export interface Agent extends Resource<
"AWS.Bedrock.Agent",
AgentProps,
{
/**
* The unique identifier of the agent.
*/
agentId: string;
/**
* The ARN of the agent.
*/
agentArn: string;
/**
* Name of the agent.
*/
agentName: string;
/** The DRAFT version identifier (always `"DRAFT"`). */
agentVersion: string;
/** The ARN of the role the agent assumes. */
agentResourceRoleArn: string;
/**
* Name of the auto-created execution role. `undefined` when an explicit
* {@link AgentProps.agentResourceRoleArn} is used.
*/
roleName: string | undefined;
}
> {}
/**
* An Amazon Bedrock agent — a foundation model driven by natural-language
* instructions that can orchestrate multi-step tasks.
*
* `Agent` owns the lifecycle of the agent's DRAFT version. An IAM execution
* role is created automatically (trusted by `bedrock.amazonaws.com`, granted
* `bedrock:InvokeModel` on the foundation model) unless an explicit
* `agentResourceRoleArn` is supplied. After every create/update the agent is
* prepared (unless `prepare: false`) so it is immediately invocable and can
* back an {@link AgentAlias}.
*
* ### Creating Agents
* **Example:** Minimal Agent
* ```typescript
* import * as Bedrock from "@alchemy.run/aws/Bedrock";
*
* const agent = yield* Bedrock.Agent("assistant", {
* foundationModel: "us.anthropic.claude-3-5-sonnet-20240620-v1:0",
* instruction:
* "You are a helpful assistant that answers questions concisely.",
* });
* ```
*
* **Example:** Agent with a Guardrail and Custom Session TTL
* ```typescript
* const agent = yield* Bedrock.Agent("assistant", {
* foundationModel: "us.anthropic.claude-3-5-sonnet-20240620-v1:0",
* instruction: "You are a careful, policy-compliant support agent.",
* idleSessionTTL: "30 minutes",
* guardrailConfiguration: {
* guardrailIdentifier: guardrail.guardrailId,
* guardrailVersion: "DRAFT",
* },
* });
* ```
*
* **Example:** Agent with Long-Term Memory
* ```typescript
* // Session summaries are retained for 30 days and readable at runtime
* // through the GetAgentMemory binding.
* const agent = yield* Bedrock.Agent("assistant", {
* foundationModel: "us.anthropic.claude-3-5-sonnet-20240620-v1:0",
* instruction: "You are a helpful assistant that remembers past sessions.",
* memoryConfiguration: {
* enabledMemoryTypes: ["SESSION_SUMMARY"],
* storage: "30 days",
* },
* });
* ```
*
* @resource
*/
export const Agent = Resource<Agent>("AWS.Bedrock.Agent");
/** Map the declared memory props onto the wire `MemoryConfiguration`. */
const toWireMemoryConfiguration = (
memory: AgentMemoryConfiguration | undefined,
): bedrock.MemoryConfiguration | undefined =>
memory === undefined
? undefined
: {
enabledMemoryTypes: [...memory.enabledMemoryTypes],
storageDays: toWireDays(memory.storage),
sessionSummaryConfiguration: memory.sessionSummaryConfiguration,
};
/** Agent status values from which no further transition is pending. */
const _AGENT_SETTLED = new Set(["NOT_PREPARED", "PREPARED", "FAILED"]);
/** Agent status values indicating an in-flight transition to wait out. */
const AGENT_TRANSIENT = new Set(["CREATING", "UPDATING", "PREPARING", "VERSIONING"]);
/**
* A freshly created IAM role is eventually consistent; `createAgent` can
* transiently reject a role it cannot yet assume with a `ValidationException`.
* Wrapped in an explicitly-typed generic helper so the `Effect.retry`
* conditional return type does not leak into declaration emit and widen the
* provider layer's requirement to `unknown` (see PATTERNS §7).
*/
const retryWhileRoleAssumeFails = <A, E extends { _tag: string }, R>(
self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
Effect.retry(self, {
while: (e) =>
e._tag === "ValidationException" &&
"message" in e &&
typeof e.message === "string" &&
e.message.toLowerCase().includes("unable to assume"),
schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(10)]),
});
export const AgentProvider = () =>
Provider.effect(
Agent,
Effect.gen(function* () {
const createName = Effect.fn(function* (id: string, props: AgentProps) {
return props.agentName ?? (yield* createPhysicalName({ id, maxLength: 100 }));
});
const createRoleName = (id: string) => createPhysicalName({ id, maxLength: 64 });
const getAgentOrUndefined = Effect.fn(function* (agentId: string) {
return yield* bedrock.getAgent({ agentId }).pipe(
Effect.map((r) => r.agent),
Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
);
});
const findByName = Effect.fn(function* (name: string) {
const pages = yield* bedrock.listAgents.pages({}).pipe(Stream.runCollect);
const summary = Array.from(pages)
.flatMap((page) => page.agentSummaries ?? [])
.find((s) => s.agentName === name);
return summary?.agentId;
});
const fetchObservedTags = Effect.fn(function* (resourceArn: string) {
return yield* bedrock.listTagsForResource({ resourceArn }).pipe(
Effect.map((r) => (r.tags ?? {}) as Record<string, string>),
Effect.catchTag("ResourceNotFoundException", () =>
Effect.succeed({} as Record<string, string>),
),
);
});
// Poll the agent to a settled (non-transient) status. Bounded: creation
// and preparation both complete within seconds to ~1 minute.
const waitForSettled = Effect.fn(function* (agentId: string) {
return yield* bedrock.getAgent({ agentId }).pipe(
Effect.map((r) => r.agent),
Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
Effect.repeat({
schedule: Schedule.fixed("3 seconds"),
until: (agent) => agent === undefined || !AGENT_TRANSIENT.has(agent.agentStatus),
times: 40,
}),
);
});
const ensureExecutionRole = Effect.fn(function* ({
id,
roleName,
region,
accountId,
foundationModel,
}: {
id: string;
roleName: string;
region: string;
accountId: string;
foundationModel: string;
}) {
const tags = yield* createInternalTags(id);
const role = yield* iam
.createRole({
RoleName: roleName,
AssumeRolePolicyDocument: JSON.stringify({
Version: "2012-10-17",
Statement: [
{
Effect: "Allow",
Principal: { Service: "bedrock.amazonaws.com" },
Action: "sts:AssumeRole",
Condition: {
StringEquals: { "aws:SourceAccount": accountId },
ArnLike: {
"aws:SourceArn": `arn:aws:bedrock:${region}:${accountId}:agent/*`,
},
},
},
],
}),
Tags: Object.entries(tags).map(([Key, Value]) => ({ Key, Value })),
})
.pipe(
Effect.catchTag("EntityAlreadyExistsException", () =>
iam.getRole({ RoleName: roleName }),
),
);
yield* iam.putRolePolicy({
RoleName: roleName,
PolicyName: "BedrockAgentInvokeModel",
PolicyDocument: JSON.stringify({
Version: "2012-10-17",
Statement: [
{
Effect: "Allow",
Action: ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"],
Resource: bedrockModelArns(region, accountId, foundationModel),
},
],
}),
});
return role.Role.Arn;
});
return Agent.Provider.of({
stables: ["agentId", "agentArn", "agentName"],
list: () =>
Effect.gen(function* () {
const { region, accountId } = yield* AWSEnvironment.current;
const pages = yield* bedrock.listAgents.pages({}).pipe(Stream.runCollect);
const summaries = Array.from(pages).flatMap((page) => page.agentSummaries ?? []);
return summaries.map((s) => ({
agentId: s.agentId,
agentArn: `arn:aws:bedrock:${region}:${accountId}:agent/${s.agentId}`,
agentName: s.agentName,
agentVersion: "DRAFT",
agentResourceRoleArn: "",
roleName: undefined as string | undefined,
}));
}),
read: Effect.fn(function* ({ id, olds, output }) {
const agentId =
output?.agentId ??
(yield* findByName(
output?.agentName ?? (yield* createName(id, olds ?? ({} as AgentProps))),
));
if (agentId === undefined) return undefined;
const agent = yield* getAgentOrUndefined(agentId);
if (agent === undefined || agent.agentStatus === "DELETING") {
return undefined;
}
const attrs = {
agentId: agent.agentId,
agentArn: agent.agentArn,
agentName: agent.agentName,
agentVersion: agent.agentVersion ?? "DRAFT",
agentResourceRoleArn: agent.agentResourceRoleArn,
roleName: output?.roleName,
};
const tags = yield* fetchObservedTags(agent.agentArn);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}),
diff: Effect.fn(function* ({ id, news, olds }) {
if (!isResolved(news)) return undefined;
const oldName = yield* createName(id, olds ?? ({} as AgentProps));
const newName = yield* createName(id, news ?? ({} as AgentProps));
if (oldName !== newName) {
return { action: "replace" } as const;
}
// foundationModel, instruction, description, guardrail, TTL, and
// tags all converge via updateAgent.
}),
reconcile: Effect.fn(function* ({ id, news = {} as AgentProps, output, session }) {
const { accountId, region } = yield* AWSEnvironment.current;
const name = output?.agentName ?? (yield* createName(id, news));
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...news.tags, ...internalTags };
// Ensure the execution role first — the agent cannot exist without
// one. Managed unless an explicit agentResourceRoleArn is provided.
let roleArn = news.agentResourceRoleArn;
let roleName = output?.roleName;
if (roleArn === undefined) {
roleName = roleName ?? (yield* createRoleName(id));
roleArn = yield* ensureExecutionRole({
id,
roleName,
region,
accountId,
foundationModel: news.foundationModel,
});
}
// 1. OBSERVE — cloud state is authoritative; output is only an id
// cache. Fall back to a name lookup after state loss.
let agent = output?.agentId ? yield* getAgentOrUndefined(output.agentId) : undefined;
if (agent === undefined) {
const foundId = yield* findByName(name);
if (foundId !== undefined) {
agent = yield* getAgentOrUndefined(foundId);
}
}
if (agent === undefined) {
// 2. ENSURE — create.
const created = yield* retryWhileRoleAssumeFails(
bedrock.createAgent({
agentName: name,
foundationModel: news.foundationModel,
instruction: news.instruction,
description: news.description,
agentResourceRoleArn: roleArn,
idleSessionTTLInSeconds: toWireSeconds(news.idleSessionTTL),
customerEncryptionKeyArn: news.customerEncryptionKeyArn,
guardrailConfiguration: news.guardrailConfiguration,
memoryConfiguration: toWireMemoryConfiguration(news.memoryConfiguration),
tags: desiredTags,
}),
);
agent = created.agent;
agent = (yield* waitForSettled(agent.agentId)) ?? agent;
} else {
// 3. SYNC — wait for any in-flight transition, then update.
agent = (yield* waitForSettled(agent.agentId)) ?? agent;
yield* bedrock.updateAgent({
agentId: agent.agentId,
agentName: name,
foundationModel: news.foundationModel,
instruction: news.instruction,
description: news.description,
agentResourceRoleArn: roleArn,
idleSessionTTLInSeconds: toWireSeconds(news.idleSessionTTL),
customerEncryptionKeyArn: news.customerEncryptionKeyArn,
guardrailConfiguration: news.guardrailConfiguration,
memoryConfiguration: toWireMemoryConfiguration(news.memoryConfiguration),
});
agent = (yield* waitForSettled(agent.agentId)) ?? agent;
}
const agentId = agent.agentId;
const agentArn = agent.agentArn;
// 3b. SYNC TAGS — diff against OBSERVED cloud tags (create-time tags
// only apply on first create; adoption may carry foreign tags).
const observedTags = yield* fetchObservedTags(agentArn);
const { upsert, removed } = diffTags(observedTags, desiredTags);
if (upsert.length > 0) {
yield* bedrock.tagResource({
resourceArn: agentArn,
tags: Object.fromEntries(upsert.map(({ Key, Value }) => [Key, Value])),
});
}
if (removed.length > 0) {
yield* bedrock.untagResource({
resourceArn: agentArn,
tagKeys: removed,
});
}
// 4. PREPARE — compile the DRAFT so the agent is invocable and can
// back an alias. Bounded poll to PREPARED/FAILED.
if (news.prepare !== false) {
yield* bedrock.prepareAgent({ agentId });
agent = (yield* waitForSettled(agentId)) ?? agent;
}
yield* session.note(agentArn);
return {
agentId,
agentArn,
agentName: name,
agentVersion: agent.agentVersion ?? "DRAFT",
agentResourceRoleArn: roleArn,
roleName,
};
}),
delete: Effect.fn(function* ({ output }) {
yield* bedrock
.deleteAgent({
agentId: output.agentId,
skipResourceInUseCheck: true,
})
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
// Tear down the managed execution role (absent when an explicit
// agentResourceRoleArn was supplied). Every step tolerates a
// partially or fully removed role.
if (output.roleName !== undefined) {
const roleName = output.roleName;
yield* iam
.deleteRolePolicy({
RoleName: roleName,
PolicyName: "BedrockAgentInvokeModel",
})
.pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
yield* iam
.deleteRole({ RoleName: roleName })
.pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
}
}),
});
}),
);