BMA preview REST API reference

This reference describes the session, event, and item operations used by the preview examples. Use an AWS SigV4-signed request to the regional bedrock-mantle endpoint. The signing service is bedrock-mantle.

Operations

Use the IDs returned by the service. Treat session IDs, environment IDs, turn IDs, and pagination cursors as opaque values.

Create a session

Request

POST /openai/v1/agents/sessions
Content-Type: application/json

{
  "agent": {
    "model": "openai.gpt-5.6-luna",
    "instructions": "Use the workspace tools to complete the user's task."
  },
  "environment": {
    "type": "self_hosted",
    "workspace_directory": "/path/to/workspace",
    "capability_directories": ["/path/to/workspace/skills"]
  },
  "role_arn": "arn:aws:iam::123456789012:role/BedrockManagedAgentsPreviewInferenceServiceRole",
  "stream": false
}

Unknown or unsupported configuration fields can result in a validation error. Use the documented preview surface rather than copying an OpenAI-hosted Agents API request without adapting it for BMA.

Environment configuration

For a self-hosted environment:

{
  "type": "self_hosted",
  "workspace_directory": "/path/to/workspace",
  "capability_directories": ["/path/to/workspace/skills"]
}

For an AgentCore Runtime environment:

{
  "type": "aws_bedrock_agentcore",
  "runtime_arn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/example-runtime",
  "runtime_qualifier": "DEFAULT",
  "workspace_directory": "/mnt/workspace",
  "capability_directories": ["/mnt/workspace/skills"]
}

workspace_directory is a path in the execution environment. capability_directories identifies directories that contain skills and other discoverable capabilities. Use absolute paths. The schema permits at most 32 unique capability-directory entries.

runtime_arn is required for aws_bedrock_agentcore. Use a Runtime in the intended account and Region, and configure the session role to invoke and stop that Runtime. runtime_qualifier selects the Runtime endpoint; the example uses DEFAULT.

Response

A JSON session resource includes:

A newly created self-hosted session can be idle before an exec server is attached. Attach the environment before asking it to execute commands.

List and retrieve sessions

List sessions:

python3 bma_client.py GET '/openai/v1/agents/sessions?limit=20&order=desc'

The list operation accepts limit, order, after, and agent_id. order is asc or desc. Pass the previous page's last_id as after when has_more is true.

Retrieve one session:

python3 bma_client.py GET "/openai/v1/agents/sessions/${SESSION_ID}"

Submit events

Messages and cancellation requests are submitted through the same endpoint. The request body must contain a nonempty events array.

Message event:

{
  "events": [{
    "type": "agent.session.input.message",
    "input": [{
      "role": "user",
      "content": [{"type": "input_text", "text": "Run the hello-docs skill."}]
    }]
  }]
}

Cancel event:

{"events":[{"type":"agent.session.input.cancel"}]}

The preview examples use text input. An accepted input event does not mean that the resulting turn has finished.

Stream events

Send GET to the session's /events path and accept text/event-stream. Parse SSE frames rather than attempting to deserialize the entire response as one JSON object.

Events report changes in session state and turn progress, including generated text, command output, completion, failure, and cancellation. Keep your event parser tolerant of event types that it does not use, while validating fields that it consumes. Use durable items to reconcile after a disconnected stream.

See stream progress for an executable example.

List items

python3 bma_client.py GET "/openai/v1/agents/sessions/${SESSION_ID}/items?limit=100&order=asc"

The list response includes data, has_more, first_id, and last_id. A message item contains its role and content. A command-execution item can include its command, working directory, output, exit code, and duration. An MCP-call item includes its server label, tool name, arguments, result, and status.

Delete a session

python3 bma_client.py DELETE "/openai/v1/agents/sessions/${SESSION_ID}"

The deletion acknowledgement identifies the deleted session. Once deleted, the session is no longer available for continued work. Clean up separately provisioned resources as described in cleanup.

Errors and retries

Capture response error details and the request ID when troubleshooting. Retry read operations with bounded exponential backoff. Before retrying a create or input submission after a network interruption, check whether it was accepted to avoid duplicate sessions or turns.