> **Experimental**
>
> `@aws-cdk/aws-bedrock-alpha` is an [**experimental**](/stability) (alpha) package: its API may change in any release, without a major version bump.
# Agent

Class to create (or import) an Agent with CDK.

Extends: Construct › Resource › AgentBase › Agent
Implements: IAgent, IResource, IGrantable, IEnvironmentAware, IConstruct, IDependable

- Stability: [Experimental](/cdk/api/stability.html)
- CloudFormation: [`AWS::Bedrock::Agent`](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-bedrock-agent.html)
- Source: [`bedrock/agents/agent.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0-alpha.0/packages/@aws-cdk/aws-bedrock-alpha/bedrock/agents/agent.ts#L341)

## Example

```ts
const parserFunction = new lambda.Function(this, 'ParserFunction', {
  runtime: lambda.Runtime.PYTHON_3_10,
  handler: 'index.handler',
  code: lambda.Code.fromAsset('lambda'),
});

const agent = new bedrock.Agent(this, 'Agent', {
  foundationModel: bedrock.BedrockFoundationModel.AMAZON_NOVA_LITE_V1,
  instruction: 'You are a helpful assistant.',
  promptOverrideConfiguration: bedrock.PromptOverrideConfiguration.withCustomParser({
    parser: parserFunction,
    preProcessingStep: {
      stepType: bedrock.AgentStepType.PRE_PROCESSING,
      useCustomParser: true
    }
  })
});
```

## Initializer

```ts
new Agent(scope: Construct, id: string, props: AgentProps)
```

## Construct Props

- `actionGroups`: [AgentActionGroup](/cdk/api/v2/docs/@aws-cdk_aws-bedrock-alpha.AgentActionGroup.html)[] — The Action Groups associated with the agent.

  **Default:** Only default action groups (UserInput and CodeInterpreter) are added

- `agentCollaboration`: [AgentCollaboration](/cdk/api/v2/docs/@aws-cdk_aws-bedrock-alpha.AgentCollaboration.html) — Configuration for agent collaboration settings, including AgentCollaboratorType and AgentCollaborators.

  **Default:** No agent collaboration configuration.

  This property allows you to define how the agent collaborates with other agents
  and what collaborators it can work with.

- `agentName`: string — The name of the agent.

  **Default:** A name is generated by CDK. Supported pattern : ^([0-9a-zA-Z][_-]?){1,100}$

  This will be used as the physical name of the agent.

- `codeInterpreterEnabled`: boolean = false — Select whether the agent can generate, run, and troubleshoot code when trying to complete a task.

- `customOrchestrationExecutor`: [CustomOrchestrationExecutor](/cdk/api/v2/docs/@aws-cdk_aws-bedrock-alpha.CustomOrchestrationExecutor.html) — The Lambda function to use for custom orchestration.

  **Default:** Default orchestration

  If provided, custom orchestration will be used.
  If not provided, default orchestration will be used.

- `description`: string — A description of the agent.

  **Default:** No description is provided.

- `existingRole`: [IRole](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IRole.html) — An existing IAM Role to associate with this agent.

  **Default:** A new role is created for you.

  Use this property when you want to reuse an existing IAM role rather than create a new one.
  The role must have a trust policy that allows the Bedrock service to assume it.

- `forceDelete`: boolean = false — Whether to delete the resource even if it's in use.

- `foundationModel`: [IBedrockInvokable](/cdk/api/v2/docs/@aws-cdk_aws-bedrock-alpha.IBedrockInvokable.html) (required) — The foundation model used for orchestration by the agent.

- `guardrail`: [IGuardrail](/cdk/api/v2/docs/@aws-cdk_aws-bedrock-alpha.IGuardrail.html) — The guardrail that will be associated with the agent.

  **Default:** No guardrail is provided.

- `idleSessionTTL`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) — How long sessions should be kept open for the agent.

  **Default:** 10 minutes

  If no conversation occurs
  during this time, the session expires and Amazon Bedrock deletes any data
  provided before the timeout.

- `instruction`: string (required) — The instruction used by the agent.

  This determines how the agent will perform his task.
  This instruction must have a minimum of 40 characters.

- `kmsKey`: [IKey](/cdk/api/v2/docs/aws-cdk-lib.aws_kms.IKey.html) — The KMS key of the agent if custom encryption is configured.

  **Default:** An AWS managed key is used.

- `memory`: [Memory](/cdk/api/v2/docs/@aws-cdk_aws-bedrock-alpha.Memory.html) — The type and configuration of the memory to maintain context across multiple sessions and recall past interactions.

  **Default:** No memory will be used. Agents will retain context from the current session only.

  This can be useful for maintaining continuity in multi-turn conversations and recalling user preferences
  or past interactions.

- `promptOverrideConfiguration`: [PromptOverrideConfiguration](/cdk/api/v2/docs/@aws-cdk_aws-bedrock-alpha.PromptOverrideConfiguration.html) — Overrides some prompt templates in different parts of an agent sequence configuration.

  **Default:** No overrides are provided.

- `shouldPrepareAgent`: boolean = false — Specifies whether to automatically update the `DRAFT` version of the agent after making changes to the agent.

  The `DRAFT` version can be continually iterated
  upon during internal development.

- `userInputEnabled`: boolean = false — Select whether the agent can prompt additional information from the user when it does not have enough information to respond to an utterance.

## Properties

- `actionGroups`: [AgentActionGroup](/cdk/api/v2/docs/@aws-cdk_aws-bedrock-alpha.AgentActionGroup.html)[] — action groups associated with the ageny.

- `agentArn`: string — The ARN of the agent.

- `agentId`: string — The unique identifier for the agent.

- `agentVersion`: string — The version of the agent.

- `env`: [ResourceEnvironment](/cdk/api/v2/docs/aws-cdk-lib.interfaces.ResourceEnvironment.html) — The environment this resource belongs to.

  For resources that are created and managed in a Stack (those created by
  creating new class instances like `new Role()`, `new Bucket()`, etc.), this
  is always the same as the environment of the stack they belong to.

  For referenced resources (those obtained from referencing methods like
  `Role.fromRoleArn()`, `Bucket.fromBucketName()`, etc.), they might be
  different than the stack they were imported into.

- `grantPrincipal`: [IPrincipal](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IPrincipal.html) — The principal to grant permissions to.

- `guardrail`: [IGuardrail](/cdk/api/v2/docs/@aws-cdk_aws-bedrock-alpha.IGuardrail.html) — The guardrail that will be associated with the agent.

- `kmsKey`: [IKey](/cdk/api/v2/docs/aws-cdk-lib.aws_kms.IKey.html) — Optional KMS encryption key associated with this agent.

- `lastUpdated`: string — When this agent was last updated.

- `name`: string — The name of the agent.

- `node`: [Node](/cdk/api/v2/docs/constructs.Node.html) — The tree node.

- `PROPERTY_INJECTION_ID`: string (static) — Uniquely identifies this class.

- `role`: [IRole](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IRole.html) — The IAM role associated to the agent.

- `stack`: [Stack](/cdk/api/v2/docs/aws-cdk-lib.Stack.html) — The stack in which this resource is defined.

- `testAlias`: [IAgentAlias](/cdk/api/v2/docs/@aws-cdk_aws-bedrock-alpha.IAgentAlias.html) — Default alias of the agent.

## Methods

- `addActionGroup(actionGroup: AgentActionGroup): void` — Adds an action group to the agent and configures necessary permissions.

  **Parameters**

  - `actionGroup` — - The action group to add.

- `addActionGroups(...actionGroups: AgentActionGroup[]): void` — Configuration for agent collaboration.

- `addGuardrail(guardrail: IGuardrail): void` — Add guardrail to the agent.

- `applyCrossStackReferenceStrength(strength: ReferenceStrength): void` — Override the cross-stack reference strength for this resource.

  When set, any cross-stack reference to this resource will use the specified
  mechanism instead of the global default determined by the
  `@aws-cdk/core:defaultCrossStackReferences` context key. This is useful for
  selectively weakening specific references to avoid the "deadly embrace" problem
  without changing the app-wide default.

  **Parameters**

  - `strength` — - The reference strength to use for this resource.

- `applyRemovalPolicy(policy: RemovalPolicy): void` — Apply the given removal policy to this resource.

  The Removal Policy controls what happens to this resource when it stops
  being managed by CloudFormation, either because you've removed it from the
  CDK application or because you've made a change that requires the resource
  to be replaced.

  The resource can be deleted (`RemovalPolicy.DESTROY`), or left in your AWS
  account for data recovery and cleanup later (`RemovalPolicy.RETAIN`).

- `fromAgentAttributes(scope: Construct, id: string, attrs: AgentAttributes): IAgent` (static) — Creates an Agent reference from an existing agent's attributes.

  **Parameters**

  - `scope` — - The construct scope.
  - `id` — - Identifier of the construct.
  - `attrs` — - Attributes of the existing agent.

  **Returns:** An IAgent reference to the existing agent

- `grantInvoke(grantee: IGrantable): Grant` — Grant invoke permissions on this agent to an IAM principal.

  [disable-awslint:no-grants]

  **Parameters**

  - `grantee` — - The IAM principal to grant invoke permissions to.

  **Returns:** An IAM Grant object representing the granted permissions

- `isConstruct(x: any): boolean` (static) — Checks if `x` is a construct.

  Use this method instead of `instanceof` to properly detect `Construct`
  instances, even when the construct library is symlinked.

  Explanation: in JavaScript, multiple copies of the `constructs` library on
  disk are seen as independent, completely different libraries. As a
  consequence, the class `Construct` in each copy of the `constructs` library
  is seen as a different class, and an instance of one class will not test as
  `instanceof` the other class. `npm install` will not create installations
  like this, but users may manually symlink construct libraries together or
  use a monorepo tool: in those cases, multiple copies of the `constructs`
  library can be accidentally installed, and `instanceof` will behave
  unpredictably. It is safest to avoid using `instanceof`, and using
  this type-testing method instead.

  **Parameters**

  - `x` — Any object.

  **Returns:** true if `x` is an object created from a class which extends `Construct`.

- `isOwnedResource(construct: IConstruct): boolean` (static) — Returns true if the construct was created by CDK, and false otherwise.

- `isResource(construct: IConstruct): boolean` (static) — Check whether the given construct is a Resource.

- `metricCount(props?: MetricOptions): Metric` — Creates a CloudWatch metric for tracking agent invocations.

  **Parameters**

  - `props` — - Configuration options for the metric.

  **Returns:** A CloudWatch Metric configured for agent invocation counts

- `onEvent(id: string, options?: OnEventOptions): Rule` — Creates an EventBridge rule for agent events.

  **Parameters**

  - `id` — - Unique identifier for the rule.
  - `options` — - Configuration options for the event rule.

  **Returns:** An EventBridge Rule configured for agent events

- `toString(): string` — Returns a string representation of this construct.

- `with(...mixins: IMixin[]): IConstruct` — Applies one or more mixins to this construct.

  Mixins are applied in order. The list of constructs is captured at the
  start of the call, so constructs added by a mixin will not be visited.
  Use multiple `with()` calls if subsequent mixins should apply to added
  constructs.