AWS AgentCore

OverviewCopy Anchor Link

AWSAgentCoreProcessor sends the conversation to an agent hosted on Amazon Bedrock AgentCore Runtime and pushes the agent's replies as LLMTextFrames, so it sits where an LLM service would: after the user context aggregator, before TTS.

• On each LLMContextFrame it builds a payload from the context and calls InvokeAgentRuntime.
• Each line the agent streams back is turned into text and pushed as an LLMTextFrame, between LLMFullResponseStartFrame and LLMFullResponseEndFrame. A response is closed when no new text arrives for 1 second.

InstallationCopy Anchor Link

bun add @pipedog/aws

import { AWSAgentCoreProcessor } from "@pipedog/aws/agent_core";

PrerequisitesCopy Anchor Link

• An agent deployed to AgentCore Runtime, and its ARN.

• An IAM identity allowed bedrock-agentcore:InvokeAgentRuntime.

• Keys, in this order of precedence:

  1. awsAccessKey, awsSecretKey and awsSessionToken.
  2. The AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN environment variables.
  3. A credentialsProvider function, called for every request.

  The region comes from awsRegion, else AWS_REGION, else us-east-1.

AWSAgentCoreProcessorCopy Anchor Link

ConfigurationCopy Anchor Link

UsageCopy Anchor Link

import { AWSAgentCoreProcessor } from "@pipedog/aws/agent_core";
import type { LLMContext } from "@pipedog/core/processors/aggregators/llm_context";

const agent = new AWSAgentCoreProcessor({
  agentArn: "arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/my-agent",
  awsRegion: "us-east-1",
});
// new Pipeline([transport.input(), stt, userAggregator, agent, tts, transport.output(), ...])

By default the payload is {"prompt": "<text>"}, from the last message when it is a user or system message, and each response line is read as {"response": "<text>"}. Change both with the transformers:

const customAgent = new AWSAgentCoreProcessor({
  agentArn: "arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/my-agent",
  // Send the whole conversation instead of the last user message.
  contextToPayloadTransformer: (context: LLMContext) =>
    JSON.stringify({ messages: context.getMessages() }),
  // The agent streams `data: {"text": "..."}` lines; the processor strips `data: `.
  responseToOutputTransformer: (line: string) => {
    try {
      return (JSON.parse(line) as { text?: string }).text ?? null;
    } catch {
      return null;
    }
  },
});

A transformer that returns null skips the call (for the payload) or the line (for the output).

NotesCopy Anchor Link

• Each call gets a new X-Amzn-Bedrock-AgentCore-Runtime-Session-Id, as botocore generates one.
• A streamed text/event-stream response is split into lines as they arrive, joining a line split across two chunks. Lines must start with data: , which is stripped before the output transformer sees them. Any other response is read whole and passed to the transformer once.
• The LLMContextFrame is consumed. Other frames pass through unchanged.

Runtime notesCopy Anchor Link

Generated from pipecat.runtimes and pipecat.compat in packages/aws/package.json: ✅ means the compat smoke test passes on that runtime.

• Runs on Bun, Node, Deno and Cloudflare Workers: POST /runtimes/{arn}/invocations with fetch, signed with SigV4 on WebCrypto.
• There is no default AWS credential chain. Use keys, the environment, or credentialsProvider.
• endpointUrl and fetch replace the AgentCore host and the global fetch.