import * as bedrock from "@distilled.cloud/aws/bedrock-agent";
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 * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
/**
* A rule pointing an alias at a specific agent version (optionally with
* provisioned throughput). Omit `routingConfiguration` entirely to have
* Bedrock snapshot the current DRAFT into a new version and point the alias
* at it — the common "deploy the current agent" case.
*/
export interface AgentAliasRoutingConfig {
/** The agent version this alias routes invocations to. */
agentVersion?: string;
/** The ARN of a provisioned-throughput commitment to use. */
provisionedThroughput?: string;
}
export interface AgentAliasProps {
/**
* The id of the {@link Agent} this alias belongs to. Accepts an agent's
* `agentId` output. Changing the agent triggers a replacement.
*/
agentId: string;
/**
* Name of the alias (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.
*/
agentAliasName?: string;
/**
* A description of the alias.
*/
description?: string;
/**
* Which agent version(s) the alias routes to. When omitted, Bedrock
* snapshots the current DRAFT into a new version and routes the alias to
* it on create.
*/
routingConfiguration?: AgentAliasRoutingConfig[];
/**
* Tags to apply to the alias. Merged with internal Alchemy tags.
*/
tags?: Record<string, string>;
}
export interface AgentAlias extends Resource<
"AWS.Bedrock.AgentAlias",
AgentAliasProps,
{
/**
* The unique identifier of the agent the alias routes to.
*/
agentId: string;
/**
* The unique identifier of the alias.
*/
agentAliasId: string;
/**
* The ARN of the alias.
*/
agentAliasArn: string;
/**
* Name of the alias.
*/
agentAliasName: string;
}
> {}
/**
* An alias for an Amazon Bedrock {@link Agent} — a stable, invocable pointer
* to one or more agent versions.
*
* An alias is what applications invoke (via `bedrock-agent-runtime`
* `InvokeAgent`). Creating an alias with no `routingConfiguration` snapshots
* the agent's current DRAFT into a new immutable version and routes the alias
* to it, so redeploying an updated + prepared agent and recreating the alias
* publishes a new version.
*
* ### Creating Aliases
* **Example:** Alias Pointing at the Current 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.",
* });
*
* const alias = yield* Bedrock.AgentAlias("prod", {
* agentId: agent.agentId,
* });
* ```
*
* **Example:** Alias Pinned to a Specific Version
* ```typescript
* const alias = yield* Bedrock.AgentAlias("prod", {
* agentId: agent.agentId,
* routingConfiguration: [{ agentVersion: "3" }],
* });
* ```
*
* @resource
*/
export const AgentAlias = Resource<AgentAlias>("AWS.Bedrock.AgentAlias");
/** Alias status values indicating an in-flight transition to wait out. */
const ALIAS_TRANSIENT = new Set(["CREATING", "UPDATING"]);
export const AgentAliasProvider = () =>
Provider.effect(
AgentAlias,
Effect.gen(function* () {
const createName = Effect.fn(function* (
id: string,
props: Pick<AgentAliasProps, "agentAliasName">,
) {
return props.agentAliasName ?? (yield* createPhysicalName({ id, maxLength: 100 }));
});
const getAliasOrUndefined = Effect.fn(function* (agentId: string, agentAliasId: string) {
return yield* bedrock.getAgentAlias({ agentId, agentAliasId }).pipe(
Effect.map((r) => r.agentAlias),
Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
);
});
const findByName = Effect.fn(function* (agentId: string, name: string) {
const pages = yield* bedrock.listAgentAliases.pages({ agentId }).pipe(Stream.runCollect);
return Array.from(pages)
.flatMap((page) => page.agentAliasSummaries ?? [])
.find((s) => s.agentAliasName === name)?.agentAliasId;
});
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>),
),
);
});
const waitForSettled = Effect.fn(function* (agentId: string, agentAliasId: string) {
return yield* bedrock.getAgentAlias({ agentId, agentAliasId }).pipe(
Effect.map((r) => r.agentAlias),
Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
Effect.repeat({
schedule: Schedule.fixed("3 seconds"),
until: (alias) => alias === undefined || !ALIAS_TRANSIENT.has(alias.agentAliasStatus),
times: 40,
}),
);
});
return AgentAlias.Provider.of({
stables: ["agentId", "agentAliasId", "agentAliasArn", "agentAliasName"],
// Aliases are scoped to a parent agent — enumeration requires the
// agent id, so this returns empty (the engine keys off state).
list: () => Effect.succeed([]),
read: Effect.fn(function* ({ id, olds, output }) {
const agentId = output?.agentId ?? olds?.agentId;
if (agentId === undefined) return undefined;
const aliasId =
output?.agentAliasId ??
(yield* findByName(
agentId,
output?.agentAliasName ?? (yield* createName(id, olds ?? ({} as AgentAliasProps))),
));
if (aliasId === undefined) return undefined;
const alias = yield* getAliasOrUndefined(agentId, aliasId);
if (alias === undefined || alias.agentAliasStatus === "DELETING") {
return undefined;
}
const attrs = {
agentId: alias.agentId,
agentAliasId: alias.agentAliasId,
agentAliasArn: alias.agentAliasArn,
agentAliasName: alias.agentAliasName,
};
const tags = yield* fetchObservedTags(alias.agentAliasArn);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}),
diff: Effect.fn(function* ({ id, news, olds }) {
if (!isResolved(news)) return undefined;
if ((olds?.agentId ?? undefined) !== (news?.agentId ?? undefined)) {
return { action: "replace" } as const;
}
const oldName = yield* createName(id, olds ?? ({} as AgentAliasProps));
const newName = yield* createName(id, news ?? ({} as AgentAliasProps));
if (oldName !== newName) {
return { action: "replace" } as const;
}
// description, routingConfiguration, and tags converge via update.
}),
reconcile: Effect.fn(function* ({ id, news = {} as AgentAliasProps, output, session }) {
const name = output?.agentAliasName ?? (yield* createName(id, news));
const agentId = news.agentId;
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...news.tags, ...internalTags };
// 1. OBSERVE
let alias = output?.agentAliasId
? yield* getAliasOrUndefined(agentId, output.agentAliasId)
: undefined;
if (alias === undefined) {
const foundId = yield* findByName(agentId, name);
if (foundId !== undefined) {
alias = yield* getAliasOrUndefined(agentId, foundId);
}
}
if (alias === undefined) {
// 2. ENSURE
const created = yield* bedrock.createAgentAlias({
agentId,
agentAliasName: name,
description: news.description,
routingConfiguration: news.routingConfiguration,
tags: desiredTags,
});
alias = created.agentAlias;
alias = (yield* waitForSettled(agentId, alias.agentAliasId)) ?? alias;
} else {
// 3. SYNC
alias = (yield* waitForSettled(agentId, alias.agentAliasId)) ?? alias;
yield* bedrock.updateAgentAlias({
agentId,
agentAliasId: alias.agentAliasId,
agentAliasName: name,
description: news.description,
routingConfiguration: news.routingConfiguration,
});
alias = (yield* waitForSettled(agentId, alias.agentAliasId)) ?? alias;
}
const agentAliasId = alias.agentAliasId;
const agentAliasArn = alias.agentAliasArn;
// 3b. SYNC TAGS against observed cloud tags.
const observedTags = yield* fetchObservedTags(agentAliasArn);
const { upsert, removed } = diffTags(observedTags, desiredTags);
if (upsert.length > 0) {
yield* bedrock.tagResource({
resourceArn: agentAliasArn,
tags: Object.fromEntries(upsert.map(({ Key, Value }) => [Key, Value])),
});
}
if (removed.length > 0) {
yield* bedrock.untagResource({
resourceArn: agentAliasArn,
tagKeys: removed,
});
}
yield* session.note(agentAliasArn);
return {
agentId,
agentAliasId,
agentAliasArn,
agentAliasName: name,
};
}),
delete: Effect.fn(function* ({ output }) {
yield* bedrock
.deleteAgentAlias({
agentId: output.agentId,
agentAliasId: output.agentAliasId,
})
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
}),
});
}),
);