Managed Harness Agent user guide
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.
curlis installed on your local machine.
Create an Agent
Log on to the AgentCore console, go to the target Workspace, open the Agent Creation page, and select Managed Harness.
In the Basic Information section, configure the following parameters.
Parameter
Value
Harness
QwenPaw
Agent Template
Do Not Use Template
Agent Name
quickstart-assistantModel Connection
A verified and available connection
Model
A model under the connection
Token Quota
Disable for Now
Description
Leave empty
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.
In the Agent Asset Configuration section, do not add any assets for now.
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.
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.
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
On the Agent details page, open External Channel Configuration and then Direct Access to obtain the Endpoint and API Key.
Set
AGENTCORE_ENDPOINTandAGENTCORE_ENDPOINT_API_KEYon your application server.AGENTCORE_ENDPOINTdoes not include the/ag-ui/agentpath.ImportantThe 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>"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 |
| The conversation has started. |
| A text fragment is returned. |
| The conversation ended successfully. |
| 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.
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, |
Mount Path | Enter a subdirectory under |
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.
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.
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.
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.
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:
Create a bot on the target IM platform and obtain credentials.
In the External Channel Configuration section of the Agent, select the corresponding channel, bind the Endpoint, and enter credentials.
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".