Managed Harness Agent user guide

Updated at:
Copy as MD

Use AgentCore managed Harness to create and run Agents without writing your own Agent Loop or managing Harness processes. This topic describes the capabilities of five Harness types: QwenPaw, Qoder, Codex, Pi, and DeepSeek Harness, and explains how to create an Agent, initiate conversations through AG-UI (the protocol for application-Agent interaction), manage configurations and Sessions, and connect external access channels.

How managed Harness works

A Harness is the engine that executes the Agent Loop, responsible for calling models, executing tools, and determining the next action based on execution results. AgentCore provides five managed Harness types: QwenPaw, Qoder, Codex, Pi, and DeepSeek Harness. When you create an Agent, you can configure the model, role, tools, and Skills. External applications call Agents through the AG-UI protocol by sending requests to an Endpoint, and Agent replies are returned as individual events through SSE (Server-Sent Events). This topic is organized as follows:

  • "Quick start": Create a QwenPaw Q&A Agent and complete your first AG-UI conversation.

  • "Configure an Agent": Purpose and limitations of each configuration section.

  • "Session management": Relationships between instances, Sessions, and context, as well as concurrency, scaling, and reclamation behaviors.

  • "External access": Direct access, IM channels, and team collaboration.

  • "Capability support matrix": Capability lists for the five Harness types and platform capabilities.

Choose a Harness

QwenPaw uses a Platform model connection, Qoder uses a Qoder native model, and Codex, Pi, and DeepSeek Harness use a Platform-compatible model connection. The following table compares model selection and provider support, and context management and compression, for QwenPaw and Qoder only:

Capability

QwenPaw

Qoder

Model selection and provider support (applies only to QwenPaw and Qoder)

You can switch models and providers through platform configuration. Adjusting model parameters is not supported.

Supports configuring Qoder native models. Adjusting model parameters, generic model providers, and BYOK (Bring Your Own Key) are not supported.

Context management and compression (applies only to QwenPaw and Qoder)

Uses the QwenPaw native mechanism.

Uses the Qoder native mechanism.

Choose QwenPaw when you need to switch models or model providers through a Platform model connection. Choose Qoder when you use a Qoder native model. Codex, Pi, and DeepSeek Harness use a Platform-compatible model connection; ensure that the selected model connection is compatible with the Harness. For the capabilities of each Harness, see "Capability support matrix".

Quick start: Create a QwenPaw Q&A Agent and interact through AG-UI

This section uses QwenPaw as an example to create a Q&A Agent and receive SSE streaming replies from the application server through AG-UI. The creation process for Qoder is the same, with the only difference being the model source. See "Choose a Harness".

Prerequisites

Before you begin, ensure the following conditions are met:

  • A Workspace has been created, and you have the permission to create Agents.

  • A model connection and model have been configured as described in Manage Models.

  • curl is installed on your local machine.

Create an Agent

  1. Log on to the AgentCore console, go to the target Workspace, open the Agent Creation page, and select Managed Harness.

  2. In the Basic Information section, configure the following parameters.

    Parameter

    Value

    Harness

    QwenPaw

    Agent Template

    Do Not Use Template

    Agent Name

    quickstart-assistant

    Model Connection

    A verified and available connection

    Model

    A model under the connection

    Token Quota

    Disable for Now

    Description

    Leave empty

  3. In the File Configuration section, enter the following content as the system prompt.

    You are a Q&A assistant that helps users answer questions, organize information, and write copy. Respond in concise and accurate Chinese. When users ask for lists, use numbered lists.
  4. In the Agent Asset Configuration section, do not add any assets for now.

  5. In the Resource Configuration section, select an instance specification, keep the pre-filled Maximum Sessions per Instance and Session TTL values, and disable Auto Scaling.

  6. In the Network Configuration section, enable Allow Default NIC to Access Internet. In this example, do not enable Allow VPC Access, which means no VPC connection. In the Storage Configuration section, do not add any OSS mounts.

  7. Click Submit. After you are redirected to the details page, open Instances and Sessions, and wait until the instance and Session are ready before initiating a conversation.

Initiate a conversation through AG-UI

  1. On the Agent details page, open External Channel Configuration and then Direct Access to obtain the Endpoint and API Key.

  2. Set AGENTCORE_ENDPOINT and AGENTCORE_ENDPOINT_API_KEY on your application server. AGENTCORE_ENDPOINT does not include the /ag-ui/agent path.

    Important

    The API Key must be stored only on the application server. Do not include it in front-end code or front-end configuration.

    export AGENTCORE_ENDPOINT="<Endpoint>"
    export AGENTCORE_ENDPOINT_API_KEY="<API Key>"
  3. Run the following command to initiate a conversation.

    curl --no-buffer --request POST "${AGENTCORE_ENDPOINT%/}/ag-ui/agent" \
      --header "x-api-key: ${AGENTCORE_ENDPOINT_API_KEY}" \
      --header 'Content-Type: application/json' \
      --header 'Accept: text/event-stream' \
      --data '{"threadId":"session-001","runId":"run-001","messages":[{"id":"message-001","role":"user","content":"Please use 3 points to introduce your abilities."}],"state":{},"tools":[],"context":[],"forwardedProps":{}}'

Evaluate conversation results

In SSE events, the TEXT_MESSAGE_CONTENT event carries the reply text in its delta field. Use the following events to determine the status of a call:

Event or condition

Meaning

RUN_STARTED

The conversation has started.

TEXT_MESSAGE_CONTENT

A text fragment is returned.

RUN_FINISHED with outcome.type=success

The conversation ended successfully.

RUN_ERROR

The conversation failed or was canceled.

Connection closed without receiving an end event

The conversation was interrupted.

To continue a conversation, keep the threadId unchanged and use a new runId and message ID.

Configure an Agent

On the Agent details page, click Edit Configuration. After you make changes, click Save. The following sections describe the purpose and limitations of each configuration area.

Basic information

Parameter

Description

Harness

Select QwenPaw, Qoder, Codex, Pi, or DeepSeek Harness. For selection criteria, see "Choose a Harness".

Agent Template

Optional. Used to reuse role files and asset configurations.

Agent Name

The display name of the Agent.

Model Connection

Select a provider connection that has been configured as described in Manage Models.

Model

Select a model under the connection. Qoder uses native models.

Token Quota

Optional. Set a daily or monthly usage limit. The value must be a positive integer.

Description

Optional.

File configuration

When no template is used, enter the system prompt directly in the File Configuration section. When a template is used, role files are provided by the template and you do not need to prepare SOUL.md or AGENTS.md yourself. For template management, see Manage Agent Templates.

Agent asset configuration

You can configure the following assets in the Agent Asset Configuration section:

Asset

Configuration and limitations

Skill

Select and add from available Skills. For management, see Manage Skill.

Subagent

Configure the name, role, and responsibilities.

Tools

Bind MCP (Model Context Protocol) services. For management, see Manage MCP services.

Knowledge base

No platform-native binding entry is currently available. You can connect a knowledge base through MCP or Skills.

Credentials

Bind external system credentials. For configuration, see Credential management.

Built-in Shell and file tools do not need to be added separately. When you use a template, you can add additional Skills, but Skill names must be unique. After a new version of a template or Skill is released, verify the bound version.

Resource configuration

Parameter

Description

Specification

Defines the CPU and memory of a single instance.

Maximum Sessions per Instance

The maximum number of Sessions that each instance can host. The value must be a positive integer.

Session TTL (seconds)

The retention duration of idle Sessions after a request ends. The value must be a positive integer.

Note

This value determines when idle Sessions are reclaimed and affects the scale-in pace. For details, see "Idle reclamation and scale-in".

Auto Scaling

Enable as needed. After enabling, you must set Minimum Instances and Maximum Instances. The minimum must not exceed the maximum.

Important

When all instances reach the upper limit, new Session requests return a capacity insufficient error.

Network configuration

Network Configuration controls the Agent's access to external services. Allow Default NIC to Access Internet is used to access public websites, download resources, or call public services. Allow VPC Access is used to access the VPC associated with the Workspace; the target service must also allow access. For how external applications call Agents, see "External access".

Storage configuration

After you enable OSS mounts, the Agent can access OSS through local paths. You must obtain the required authorization before configuring mounts.

Important

You can add up to 10 mount points.

Parameter

Description

OSS Bucket

Select a Bucket that you have access to.

Directory in Bucket

Enter a non-empty relative directory, for example, reports/input.

Mount Path

Enter a subdirectory under /mnt/oss/, for example, /mnt/oss/reports. Mount paths must be unique within the same Agent.

Read-Only

Enable when only read access is needed. Disable when write access is required, and ensure that write permissions have been granted.

How configuration changes take effect

Changes to models, prompts, Skills, Subagents, MCP, and credentials support hot reload without a restart. Changes to instance specifications, images, and mount points require a restart to take effect. We recommend that you modify restart-dependent configurations after tasks are complete.

View and update the Harness version

View the Harness Version on the Agent list or the Agent details page. For example, in latest(202611101013), the value in parentheses is the tag of the current target runtime image. Sandboxes under the same Agent may run different images. The platform compares the actual tag of each instance with the current target tag to determine whether the instance needs to be updated.

  1. Open Instances and Sessions. If an Endpoint selector is available, select the Endpoint that you want to operate on, and then check the actual version and selectable status of the instances.

  2. Select one or more instances that need to be updated and click Update to Latest Version. In the dialog box, check the instance scope and the target version, and then confirm the submission. The platform rebuilds the selected Sandboxes by using the target image at the time the request is accepted.

  3. Track the results in the instance list. Confirm that the instances become available again and that the actual Harness version matches the target version. To verify your business, initiate a new Session from the corresponding Endpoint.

While the selected Sandboxes are being rebuilt, they are temporarily unavailable and running Sessions are interrupted. You can update a small number of idle instances first, and then update the remaining instances after you confirm that they have recovered. If you rebuild all available instances at the same time, the Agent may be temporarily unable to process new requests.

Session management

Instances, Sessions, and context

An instance is the computing environment that runs an Agent. A Session is a series of continuous interactions with a unique ID. Context is the information that an Agent references when processing requests, including previous conversations and tool execution results. An Agent can run multiple instances, and an instance can host multiple Sessions. Sessions within the same instance share CPU and memory, so increasing Maximum Sessions per Instance does not add computing resources.

View instances and Sessions

On the Agent details page, open Instances and Sessions to view instance status and Session counts, search by instance ID or Session ID, and view details of individual Sessions. After you create an Agent, use this page to confirm that the instance and Session are ready.

Session sources and allocation

Sessions can be created from Direct Access Endpoint calls, DingTalk, Feishu, or WeCom channels, as well as collaboration instance chats and collaboration instance Tasks. Existing Sessions continue to use their original instances. After Auto Scaling is enabled, new Sessions are preferentially allocated to ready instances that have not reached their limit. When multiple instances are available, the one with more existing Sessions is preferred. When capacity is insufficient, the platform adds instances according to the configuration, and new Sessions are executed after the instances are ready.

Concurrency and auto scaling

Regular conversation requests within the same Session are processed serially; subsequent requests are queued. Different Sessions can be processed concurrently. After Auto Scaling is enabled, the platform calculates the required number of instances based on the Session count and Maximum Sessions per Instance, with Minimum Instances as the lower bound and Maximum Instances as the upper bound. The Session count used for capacity calculation includes Sessions that have not yet been reclaimed and new Sessions being requested. After a request ends, the Session is retained for a period and continues to occupy capacity. For example, when each instance supports 5 Sessions, Minimum Instances is 1, and Maximum Instances is 3:

Sessions

Required instances

0–5

1

6–10

2

11–15

3

When all instances reach the upper limit, new Session requests return a capacity insufficient error. New instances require startup time. After Auto Scaling is disabled, the platform does not automatically add instances.

Idle reclamation and scale-in

Sessions with active or queued requests are not reclaimed due to idle timeout. Session TTL determines how long an idle Session is retained after a request ends. For example, 600 means the Session is reclaimed after 10 minutes of idle time. After a Session is reclaimed, it no longer occupies capacity. When you make a new request with the original Session ID, a new instance is allocated.

After Auto Scaling is enabled, the platform only reclaims surplus instances that have no Sessions and retains at least Minimum Instances. When Sessions are spread across multiple instances, they are not consolidated. Instead, scale-in occurs after Sessions are reclaimed. A longer TTL retains Sessions longer and delays scale-in. A shorter TTL releases capacity faster but increases the likelihood of instance reallocation.

Context, history, and working files

When conversations become long, the Harness compresses historical context to free up space. QwenPaw and Qoder each use their own native mechanism. After compression, not all original conversation content may be retained.

Native Sessions are backed up periodically and restored on startup. The original Session ID can reference saved history. TTL does not determine how long history is retained, and Session reclamation does not delete history. Restoration does not automatically resume interrupted requests or tool operations.

Warning

During abnormal interruptions, content from the last 5 seconds that has not been backed up may be lost.

Each Session has an independent working directory. Different Sessions of the same Agent can share files through the shared/ directory. Working files are not included in conversation history backups. To persist working files, save them to an OSS mount path.

External access

Direct access

Direct access is used to call Agents from your application server. The server sends requests through the AG-UI protocol and displays SSE-returned text to the client. For how to obtain the Endpoint and API Key, call examples, and event evaluation methods, see "Initiate a conversation through AG-UI" and "Evaluate conversation results".

Connect IM channels

You can connect an Agent to DingTalk, Feishu, or WeCom:

  1. Create a bot on the target IM platform and obtain credentials.

  2. In the External Channel Configuration section of the Agent, select the corresponding channel, bind the Endpoint, and enter credentials.

  3. After saving the configuration, @ the bot in a test group to verify the conversation.

    For complete configuration instructions, see Connect an Agent to an IM Bot.

Use team collaboration

After joining a Team, you can participate in chats, tasks, and subtasks. Collaboration instance chats and collaboration instance Tasks also create Sessions. See "Session sources and allocation".

Capability support matrix

The following table shows the capabilities supported by the five Harness types. "Not supported" in the table indicates current unavailability. For configuration methods and limitations of each capability, see the corresponding section.

Capability

QwenPaw

Qoder

Codex

Pi

DeepSeek Harness

Custom role and system prompt

Supported

Supported

Supported

Supported

Supported

Model selection

Platform model connection

Qoder native model

Platform-compatible model connection

Platform-compatible model connection

Platform-compatible model connection

Shell command execution

Supported

Supported

Supported

Supported

Supported

File read, create, and modify

Supported

Supported

Supported

Supported

Supported

Skill loading

Supported

Supported

Supported

Supported

Supported

MCP tool invocation

Supported

Supported

Supported

Supported

Supported

Browser operations

Native browser tool

Calls Playwright through the command tool

Uses the native Playwright MCP by default

Calls Playwright through the command tool

Calls Playwright through the command tool

Web Search

Built-in search tool

Native tool or a configured search service

Configure a search Skill or MCP

Built-in search tool; a search service can also be configured

Built-in search tool; a search service can also be configured

Image input and screenshot understanding

Supported

Supported

Supported

Supported

Supported

File attachment input

Supported

Supported

Supported

Supported

Supported

File delivery and download links

Supported

Supported

Supported

Supported

Supported

Subagent invocation

Supported

Supported

Supported

Supported

Supported

Access external services with bound credentials

Supported

Supported

Supported

Supported

Supported

Multi-turn conversations

Supported

Supported

Supported

Supported

Supported

Historical Session saving and restoration

Supported

Supported

Supported

Supported

Supported

Session working directory

Supported

Supported

Supported

Supported

Supported

AgentLoop Trace

Supported

Supported

Supported

Supported

Supported

Platform-native knowledge base binding

Not supported

Not supported

Not supported

Not supported

Not supported

Platform-native long-term memory binding

Not supported

Not supported

Not supported

Not supported

Not supported

  • Image input and screenshot understanding require the selected model to support images. Other types of attachments can be read by tools, which does not mean native audio and video understanding is uniformly supported.

  • The model connection must be compatible with the selected Harness. Choosing Codex or DeepSeek Harness does not require a model from the vendor of the same name.

  • Browser and search are configured separately. To use an external search service, configure the corresponding access credentials and network.

  • Knowledge base and memory services can be connected through MCP or Skills.

Platform capabilities

The following capabilities are provided by AgentCore and apply to all five Harness types above.

Capability

Support scope

API invocation

AG-UI requests and SSE streaming responses

Instance specifications

Configure the CPU and memory of a single instance

Session concurrency

Different Sessions run concurrently. Regular conversation requests within the same Session are executed in order

Auto scaling

Configure the minimum and maximum number of instances and the Session capacity of a single instance

Network access

Configure Internet access and Workspace VPC access

External storage mounts

Use configured persistent storage

Version and configuration management

Manage Agent configurations and versions

External channels

Connect to DingTalk, Feishu, and WeCom through platform connectors

What's next

After completing the quick start, you can continue to enhance your Agent in the following areas:

  • Add Skills, Subagents, MCP tools, and external system credentials to expand Agent capabilities. For configuration, see "Agent asset configuration".

  • Mount OSS directories and enable Allow VPC Access so that the Agent can read and write persistent files and access the VPC associated with the Workspace. For configuration, see "Storage configuration" and "Network configuration".

  • Adjust Maximum Sessions per Instance, Session TTL, and Auto Scaling based on concurrency requirements to prevent new Session requests from returning capacity insufficient errors. For calculation rules, see "Concurrency and auto scaling".

  • Connect the Agent to DingTalk, Feishu, or WeCom channels, or join a Team for collaboration. See "External access".