AWS AgentCore live sessions require a qualified AgentCore pr

Error message

AWS AgentCore live sessions require a qualified AgentCore profile

What it means

CapabilityLiveSession.create requires aws_agentcore sessions to include an agentCoreProfile describing the qualified AgentCore setup. Without it the runner cannot configure the AWS AgentCore transport and throws during create().

Source

Thrown at packages/paperclip-runner/src/live/live-session.ts:871

  readonly #now: () => Date;
  readonly #sessions = new Map<string, CapabilityLiveSession>();

  constructor(options: CapabilityLiveSessionServiceOptions = {}) {
    this.#store = options.store ?? new InMemoryCapabilityLiveSessionStore();
    this.#transportFactory = options.transportFactory ?? createCapabilityRunnerdCodexTransport;
    this.#transportOptions = options.transportOptions ?? {};
    this.#now = options.now ?? (() => new Date());
  }

  async create(input: CreateCapabilityLiveSessionInput = {}): Promise<CapabilityLiveSession> {
    if (input.provider === "acpx" && input.acpxAgent === "pi") {
      throw new Error("The Pi ACPX profile is not available");
    }
    if (input.provider === "claude_managed" && !input.managedProfile) {
      throw new Error("Claude Managed live sessions require a qualified managed profile");
    }
    if (input.provider === "aws_agentcore" && !input.agentCoreProfile) {
      throw new Error("AWS AgentCore live sessions require a qualified AgentCore profile");
    }
    if (
      (input.provider === "claude_managed" || input.provider === "aws_agentcore") &&
      !input.requestedModel?.trim()
    ) {
      throw new Error("Managed live sessions require an explicit qualified model");
    }
    const port = new CapabilityMockControlPlaneAdapter(input.seed);
    const seedState = port.serialize();
    await port.start();
    const state = port.snapshot();
    const sessionId = input.sessionId ?? randomUUID();
    const runId = input.runId ?? randomUUID();
    const acpxProfile = input.provider === "acpx"
      ? resolveQualifiedAcpxProfile(input.acpxAgent ?? "codex", requireNonEmpty(input.requestedModel ?? "", "requested_model"))
      : null;
    const capabilities = [...(input.capabilities ?? [])];
    const scenario = input.scenario ?? { id: "capability-live-default" };

View on GitHub (pinned to 01ad858492)

Solutions

Supply a valid input.agentCoreProfile when using provider 'aws_agentcore'
Run/complete the AgentCore qualification step that produces the profile and pass it through
Fix config plumbing so the profile is loaded from env/config before create()
Choose a supported provider if AgentCore is not set up

Example fix

// before
await liveSession.create({ provider: 'aws_agentcore' });
// after
if (!agentCoreProfile) throw new Error('configure agentCoreProfile for aws_agentcore');
await liveSession.create({ provider: 'aws_agentcore', agentCoreProfile });

Defensive patterns

Strategy: validation

Validate before calling

if (input.provider === 'aws_agentcore' && !input.agentCoreProfile) throw new Error('agentCoreProfile required for aws_agentcore sessions');

Type guard

function hasAgentCoreProfile(input: { provider: string; agentCoreProfile?: object }): input is { provider: 'aws_agentcore'; agentCoreProfile: object } {
  return input.provider === 'aws_agentcore' && !!input.agentCoreProfile;
}

Try / catch

try {
  await liveSession.create(input);
} catch (err) {
  if (err instanceof Error && err.message.includes('require a qualified AgentCore profile')) {
    // report missing AWS AgentCore setup
  } else throw err;
}

Prevention

Complete AgentCore qualification before enabling the provider
Validate provider-specific fields at config load time
Gate aws_agentcore behind a config check for the profile

When it happens

Trigger: Calling create({ provider: 'aws_agentcore' }) with input.agentCoreProfile undefined/null, e.g. when AWS AgentCore config was never supplied.

Common situations: Missing AWS AgentCore profile in config; environment where AgentCore qualification never ran; templates defaulting to another provider then switched to aws_agentcore.

Related errors

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-02). Data as JSON: /api/errors/32ed8d55ddec3be7. Report an issue: GitHub.